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About this book 


This section contains the following information: 


Who should use this book 


This book is intended for the following people: 

* Those who work with XML data in DB2® applications and who are familiar 
with XML concepts. Readers of this document should have a general 
understanding of XML and DB2. To learn more about XML, see the 
following Web site: 
http://www.w3.org / XML 
To learn more about DB2, see the following Web site: 
http://www.ibm.com/software/data/db2/library 

* DB2 database administrators who are familiar with DB2 administration 
concepts, tools, and techniques. 

* DB2 application programmers who are familiar with SQL and with one or 
more programming languages that can be used for DB2 applications. 


How to get a current version of this book 
You can get the latest version of this book at the XML Extender Web site: 


http://www.ibm.com/software/data/db2/extenders/xmlext/library.html 


How to use this book 
This book is structured as follows: 


Part 1. Introduction 
This part provides an overview of the XML Extender and how you 
can use it in your business applications. It contains a getting-started 
scenario that helps you get up and running. 


Part 2. Administration 
This part describes how to prepare and maintain a DB2 database for 
XML data. Read this part if you need to administer a DB2 database 
that contains XML data. 
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Part 3. Programming 
This part describes how to manage your XML data. Read this part if 
you need to access and manipulate XML data in a DB2 application 
program. 


Part 4. Reference 
This part describes how to use the XML Extender administration 
commands, user-defined types, user-defined functions, and stored 
procedures. It also lists the messages and codes that the XML 
Extender issues. Read this part if you are familiar with the XML 
Extender concepts and tasks, but you need information about a 
user-defined type (UDT), user-defined function (UDF), command, 
message, metadata tables, control tables, or code. 


Part 5. Appendixes 
The appendixes describe the DTD for the document access definition, 
samples for the examples and getting started scenario, and other 
IBM® XML products. 


Highlighting conventions 
This books uses the following conventions: 


Bold text indicates: 
* Commands 
¢ Field names 
¢ Menu names 
¢ Push buttons 


Italic text indicates 
* Variable parameters that are to be replaced with a value 
* Emphasized words 
* First use of a glossary term 


Uppercase letters indicate: 
* Data types 
* Column names 
* Table names 


Example text indicates: 
* System messages 
* Values that you type 
* Coding examples 
¢ Directory names 
* File names 
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How to read syntax diagrams 


Throughout this book, the syntax of commands and SQL statements is 
described using syntax diagrams. 


Read the syntax diagrams as follows: 


* Read the syntax diagrams from left to right, from top to bottom, following 
the path of the line. 


The »»>—— symbol indicates the beginning of a statement. 


The —» symbol indicates that the statement syntax is continued on the 
next line. 


The »—— symbol indicates that a statement is continued from the previous 
line. 


The —»< symbol indicates the end of a statement. 


Diagrams of syntactical units other than complete statements start with the 
»>—— symbol and end with the —-» symbol. 


* Required items appear on the horizontal line (the main path). 


p>>—required item >< 


* Optional items appear below the main path. 


>< 


p>>—required item 


apetongi iva! 
If an optional item appears above the main path, that item has no effect on 
the execution of the statement and is used only for readability. 


--optional_item— 
p>>—required item >< 


* If you can choose from two or more items, they appear vertically, in a stack. 


If you must choose one of the items, one item of the stack appears on the 
main path. 


Re Sst ee | >< 
—required_choice2 


If choosing one of the items is optional, the entire stack appears below the 
main path. 


© Copyright IBM Corp. 1999, 2003 xi 


>>—required_item >< 
[-optional_choicel— 
optional_choice2— 


If one of the items is the default, it appears above the main path and the 
remaining choices are shown below. 


--default_choice— 
>>—required_item >< 
[-optional_choice— 
‘-optional_choice— 


* An arrow returning to the left, above the main line, indicates that an item 
that can be repeated. 


v 


>>—required_item 


repeatable_item >< 


* If the repeat arrow contains punctuation, you must separate repeated items 
with the specified punctuation. 


v 


>>—required_item repeatable_item >< 


* A repeat arrow above a stack indicates that you can repeat the items in the 
stack. 

— Keywords appear in uppercase (for example, FROM). In the XML Extender, 
keywords can be used in any case. Terms that are not keywords appear 
in lowercase letters (for example, column-name). They represent 
user-supplied names or values. 

— If punctuation marks, parentheses, arithmetic operators, or other such 
symbols are shown, you must enter them as part of the syntax. 
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Part 1. Introduction 


This part provides an overview of the XML Extender and how you can use it 
in your business applications. 
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Chapter 1. Introduction 


Introduction to XML Extender 


The IBM® DB2® Extenders family provides data and metadata management 
solutions to handle traditional data types and new, or non-traditional, types of 
data. The DB2 XML Extender helps you integrate the power of IBM’s DB2 
Universal Database’’ (DB2 UDB) DB2 Universal Database for iSeries’ with 
the flexibility of eXtensible Markup Language (XML). 


DB2’s XML Extender provides the ability to store and access XML documents, 
to generate XML documents from existing relational data, and to insert rows 
into relational tables from XML documents. XML Extender provides new data 
types, functions, and stored procedures to manage your XML data in DB2 
Relational Databases (referred to as “RDB databases” or simply “databases” in 
this book). 


The XML Extender is available for the following operating systems: 
* Windows® NT 

* Windows 2000 

+ AIX® 

* Sun Solaris 

* Linux 

* OS/390 and z/OS 

* iSeries 


Related concepts: 
° (“XML Documents” on page 3 


- (‘How DB2 and XML Extender work together” on page 5 

- [Lesson: Storing an XML document in an XM. column” on page 10 
- [‘Lesson: Composing an XML document” on page 21] 

- [/Getting Started with XML Extender” on page 8 


XML Documents 


There are many applications in the computer industry, each with their own 
strengths and weaknesses. Users today have the opportunity to choose 
whichever application best suits the requirements of the task at hand. 
However, because users tend to share data between different applications, 
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they are continually faced with the problem of replicating, transforming, 
exporting, or saving their data in formats that can be imported into other 
applications. Many of these transforming processes tend to drop some of the 
data, or they at least require that users go through the tedious process of 
ensuring that the data remains consistent. This manual checking consumes 
both time and money. 


Today, one of the ways to address this problem is for application developers 
to write Open Database Connectivity (ODBC) applications, a standard 
application programming interface (API) for accessing data in both relational 
and non-relational database management systems. These applications save the 
data in a database management system. From there, the data can be 
manipulated and presented in the form in which it is needed for another 
application. Database applications must be written to convert the data into a 
form that an application requires; however, applications change quickly and 
quickly become obsolete. Applications that convert data to HTML provide 
presentation solutions, but the data presented cannot be practically used for 
other purposes. If there were another method that separated the data from its 
presentation, this method could be used as a practical form of interchange 
between applications. 


XML—eXtensible Markup Language—has emerged to address this problem. It is 
extensible in that the language is a metalanguage that allows you to create 
your own language depending on the needs of your enterprise. You use XML 
to capture not only the data for your particular application, but also the data 
structure. Although it is not the only data interchange format, XML has 
emerged as the accepted standard. By adhering to this standard, applications 
can share data without first transforming it using proprietary formats. 


Why XML and DB2 


Because XML is now the accepted standard for data interchange, many 
applications are emerging that will be able to take advantage of it. 


Suppose you are using a particular project management application and you 
want to share some of its data with your calendar application. Your project 
management application could export tasks in XML, which could then be 
imported as-is into your calendar application. In today’s interconnected world, 
application providers have strong incentives to make an XML interchange 
format a basic feature of their application. 


Although XML solves many problems by providing a standard format for 
data interchange, some challenges remain. When building an enterprise data 
application, you must answer questions such as: 


* How often do I want to replicate the data? 
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* What kind of information must be shared between applications? 
* How can I quickly search for the information I need? 


* How can [have a particular action, such as a new entry being added, 
trigger an automatic data interchange between all my applications? 


These kinds of issues can be addressed only by a database management 
system. By incorporating the XML information and meta-information directly 
in the database, you can more efficiently obtain the XML results that your 
other applications need. This is where the XML Extender can assist you. With 
the XML Extender, you can take advantage of the power of DB2® in many 
XML applications. 


With the content of your structured XML documents in a DB2 database, you 
can combine structured XML information with traditional relational data. 
Based on the application, you can choose whether to store entire XML 
documents in DB2 as in user-defined types provided for XML data (XML data 
types), or you can map the XML content as base data types in relational 
tables. For XML data types, the XML Extender adds the power to search rich 
data types of XML element or attribute values, in addition to the structural 
text search that the text extender provides. 


What XML Extender can do for your your applications: 


* Compose or decompose contents of XML documents with one or more 
relational tables, using the XML collection method of storage and access 


How DB2 and XML Extender work together 


XML Extender provides the following features to help you manage and 
exploit XML data with DB2: 


* Administration tools to help you manage the integration of XML data in 
relational tables 

* Storage and access methods for XML data within the database 

* A data type definition (DTD) repository for you to store DTDs used to 
validate XML data 


* A mapping file called the Document Access Definition (DAD), which is 
used to map XML documents to relational data 


Administration tools: The XML Extender administration tools help you enable 
your database and table columns for XML, and map XML data to DB2® 
relational structures. The XML Extender provides the various administration 
tools to help your administration tasks. 
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You can use the following tools to complete administration tasks for the XML 
Extender: 


¢ The dxxadm command can be run from the OS command line. 
* Stored procedures can be run from the iSeries’ Navigator. 


* The XML Extender administration stored procedures allow you to invoke 
administration commands from a program. 


Storage and Access Methods: XML Extender provides two storage and access 
methods for integrating XML documents with DB2 data structures: XML 
column and XML collection. These methods have very different uses, but can 
be used in the same application. 


XML column method 
This method helps you store intact XML documents in DB2. The XML 
column method works well for archiving documents. The documents 
are inserted into columns enabled for XML and can be updated, 
retrieved, and searched. Element and attribute data can be mapped to 
DB2 tables (side tables), which can be indexed for fast search. 


XML collection method 
This method helps you map XML document structures to DB2 tables 
so that you can either compose XML documents from existing DB2 
data, or decompose XML documents, storing the untagged data in 
DB2 tables. This method is good for data interchange applications, 
particularly when the contents of XML documents are frequently 
updated. 


DTDs:The XML Extender also allows you to store DTDs, the set of 
declarations for XML elements and attributes. When a database is enabled for 
XML, a DTD repository table (DTD_REF) is created. Each row of this table 
represents a DTD with additional metadata information. Users can access this 
table to insert their own DTDs. The DTDs are used for validating the structure 
of XML documents. 


DAD files: You specify how structured XML documents are to be processed 
by the XML Extender using a document access definition (DAD) file. The DAD 
file is an XML document that maps the XML document structure to a DB2 
table. You use a DAD file both when storing XML documents in a column, or 
when composing or decomposing XML data. The DAD file specifies whether 
you are storing documents using the XML column method, or defining an 
XML collection for composition or decomposition. 


Location paths: A location path specifies the location of an element or attribute 
within an XML document. The XML Extender uses the location path to 
navigate the structure of the XML document and locate elements and 
attributes. 
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For example, a location path of /Order/Part/Shipment/Shipdate points to the 
shipdate element, that is a child of the Shipment, Part, and Order elements, as 
shown in the following example: 
<Order> 
<Part> 
<Shipment> 


<Shipdate> 
eee 


shows an example of a location path and its relationship to the 
structure of the XML document. 


Order 


pee td | 


<key > Customer Part 


Name Email 


(American Motors) (parts@am.com ) 


Key Sues ExtendedPrice Shipment 
(5) & )  C34,850.16_) cae 
ShipDai SEES 


Location path: “/Order/Part/Shipment/ShipDate”.----.----..: ee { 1998- = 19 ) ar 


Figure 1. Storing documents as structured XML documents in a DB2 table column 


The location path is used in the following situations: 
* For XML columns: 


— To identify the elements and attributes to be extracted or updated when 
using the XML Extender user-defined functions. 


— To map the content of an XML element or attribute to a side table. 


* For XML collections: To override values in the DAD file from a stored 
procedure. 


To specify the location path, the XML Extender uses a subset of the XML Path 
Language (XPath), the language for addressing parts of an XML document. 


For more information about XPath, see the following Web page: For XPath, 
see: 


http://www.w3.org/TR/xpath 
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for syntax and restrictions. 


Related concepts: 


* |“Why XML and DB2” on page 4 
“Lesson: Storing an XML document in an XML column” on page 10 


“Lesson: Composing an XML document” on page 21 


“Getting Started with XML Extender” on page 8 


Getting Started with XML Extender 


This tutorial shows you how to get started using the XML Extender to access 
and modify XML data for your applications. Two lessons are provided: 


* Storing an XML document in an XML column 
* Composing an XML documentComposing an XML document 
By following the tutorial lessons, you can set up a database using provided 


sample data, map SQL data to an XML document, store XML documents in 
the database, and then search and extract data from the XML documents. 


In the administration lessons, you use with XML Extender administration 
commands. In XML data management lessons, you will use XML Extender 
UDFs and stored procedures. Most of the examples in the rest of the book 
draw on the sample data that is used in this chapter. 


Required: To complete the lessons in this tutorial, you must have the 
following prerequisites installed: 


* DB2 Universal Database™ Version 5 Release 2 

* Optional: iSeries'” Navigator to run lesson samples 

Additionally, you must set up the administration environment. See 
up the Getting Started environment for iSeries” on page 50} for more 
information on setting up the administration environment. 

The lessons are as follows: 


¢ Store an intact XML document in a DB2 table column 


— Plan the XML user-defined type (UDT) in which to store the document 
and the XML elements and attributes to be frequently searched. 


— Set up the database and tables 

— Enable the database for XML 

— Insert the DTD into the DTD repository table 

— Prepare a DAD for an XML column 

— Add a column of XML type to an existing table 
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Enable the new column for XML 


Create indexes on the side tables 
— Store an XML document in the XML column 
— Search the XML column using XML Extender UDFs 
* Create an XML document from existing data 
— Plan the data structure of the XML document 
Set up the database and tables 
— Enable the database for XML 
— Prepare a document access definition (DAD) file for an XML collection 


Compose the XML document from existing data 
Retrieve the XML document from the database 
* Clean up the database 


Scenario for the lessons: 


In these lessons, you work for ACME Auto Direct, a company that distributes 
cars and trucks to automotive dealerships. You have been given the task to 
take information in an existing purchase order database, SALES_DB, and 
extract key information from it to be stored in XML documents. 


Choosing a method to run the tutorial lessons: 


Several methods for running the scripts and commands are provided. You can 
use the iSeries Navigator or the OS command line. 


* Use the Navigator to run the getting started lessons as stored procedures in 
a Windows® environment. 


* Use the OS command line to run scripts and SQL statements. 


Related concepts: 

* Introduction to XML Extender” on page 3 

° (“XML Documents” on page 3 

* (Why XML and DB2” on page 
‘How DB2 and XML Extender work together” on page 

* {Administration Tools” on page 41 

* (Chapter 7, “XML Extender user-defined types” on page 161 


° “XML Extender administration planning” on page 5 


as 


e 


e 


Lesson: Storing an XML document in an XML column” on page 10 
* |‘Lesson: Composing an XML document” on page 21 
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Lesson: Storing an XML document in an XML column 


The XML Extender provides a method of storing and accessing whole XML 
documents in the database. The XML column method enables you to store the 
document using the XML file types, index the column in side tables, and then 
query or search the XML document. This storage method is particularly useful 
for archival applications in which documents are not frequently updated. 


The scenario: 


You have been given the task of archiving the sales data for the service 
department. The sales data you need to work with is stored in XML 
documents that use the same DTD. 


The service department has provided a recommended structure for the XML 
documents and specified which element data they believe will be queried 
most frequently. They would like the XML documents stored in the 
SALES_TAB table in the SALES DB database and want be able to search them 
quickly. The SALES_TAB table will contain two columns with data about each 
sale, and a third column will contain the XML document. This column is 
called ORDER. 


To store this XML document in the SALES_TAB table, you will: 


1. Determine the XML Extender user-defined types (UDTs) in which to store 
the XML document, as well as which XML elements and attributes will be 
frequently queried. 

2. Set up the SALES_DB database for XML. 

3. Create the SALES_TAB table, and enable the ORDER column so that you 
can store the intact document in DB2. 

4. Insert a DTD for the XML document for validation. 

5. Store the document as an XMLVARCHAR data type 


When you enable the column, you will define side tables to be indexed for the 
structural search of the document in a document access definition (DAD) file, 
an XML document that specifies the structure of the side tables. 


The SALES_TAB is described in}Table 1| The XML column to be enabled for 
XML, ORDER, is shown in italics. 


Table 1. SALES_TAB table 


Column name Data type 

INVOICE_NUM CHAR(6) NOT NULL PRIMARY KEY 
SALES_PERSON VARCHAR(20) 

ORDER XMLVARCHAR 
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For this tutorial, you use a set of scripts to set up your environment and 
perform the steps in the lessons. The operating system command line scripts 
are in the dxxsamples library. The Navigator SQL Script Files are in the 
/dxxsamples directory. 


‘Table 2}lists the samples that are provided to complete the getting started 
tasks. 


Table 2. List of the XML collection lesson samples 


Lesson description OS command line Navigator SQL Script 
scripts File 

Create and fill SALES DB tables C_SALESDB C_SalesDb.sql 

Insert the DTD getstart.dtd into INSERTDTD InsertDTD.sql 

the DTD_REF table 

Create SALES_TAB for XML C_SALESTAB C_SalesTab.sql 

column 

Add the ORDER column to ADDORDER AddOrder.sql 

SALES TAB 

Enable the ORDER column as an Manual command EnableCol.sql 

XML column described in text 

Create indexes on side tables C_INDEX C_Index.sql 

Insert an XML document into INSERTXML InsertXML.sql 


the SALES_TAB XML column 


Query the XML document held Manual command QueryCol.sql 
in the sales_tab XML column 
through the side tables 


Removes sample tables and D_SALESDB and CleanupCol.sql 
disables column CLEANUPCLL 


Planning how to store the document: 


Before you begin working with the XML Extender to store your documents, 
you need to understand the structure of the XML document so that you can 
determine how to search the document. When planning how to search the 
document, you need to determine: 


* The XML user-defined type in which you will store the XML document 


* The XML elements and attributes that the service department will 
frequently search, so that the content of these can be stored in side tables 
and indexed to improve performance. 


The following sections will explain how to make these decisions. 


The XML document structure: 
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The XML document structure for this lesson takes information for a specific 
order that is structured by the order key as the top level, then customer, part, 
and shipping information on the next level. 


This lesson provides the sample DTD for you to use in understanding and 
validating the XML document structure. 


Determining the XML data type for the XML column: 


The XML Extender provides XML user defined types you can use to define a 
column to hold XML documents. These data types are: 


* XMLVARCHAR: for small documents stored in DB2 
* XMLCLOB: for large documents stored in DB2 
* XMLFILE: for documents stored outside DB2 


In this lesson, you will store a small document in DB2, so you will use the 
XMLVarchar data type. 


Determining elements and attributes to be searched: 


When you understand the XML document structure and the needs of the 
application, you can determine which elements and attributes will be searched 
or extracted most frequently, or those that will be the most expensive to query. 
The service department has indicated that they will be frequently querying 
the order key, customer name, price, and shipping date of an order, and they 
need quick performance for these searches. This information is contained in 
elements and attributes of the XML document structure. describes the 
location paths of each element and attribute. 


Table 3. Elements and attributes to be searched 


Data Location path 

order key /Order/@key 

customer / Order /Customer/Name 

price /Order/Part/ExtendedPrice 
shipping date /Order/Part/Shipment/ShipDate 


Mapping the XML document to the side tables: 


To map your XML documents to a side table, you must create a DAD file for 

the XML column. The DAD file is used to store the XML document in DB2. It 
also maps the XML element and attribute contents to DB2 side tables used for 
indexing, which improves search performance. 
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After identifying the elements and attributes to be searched, you determine 
how they should be organized in the side tables, how many tables and which 
columns are in what table. Organize the side tables by putting similar 
information in the same table. The document structure is also determined by 
whether the location path of any elements can be repeated more than once in 
the document. For example in our document, the part element can be 
repeated multiple times, and therefore, the price and date elements can occur 
multiple times. Elements that can occur multiple times must each be in their 
own side tables. You also must determine what DB2 base types the element or 
attribute values should use, which is determined by the format of the data. 


¢ If the data is text, choose VARCHAR. 

* If the data is an integer, choose INTEGER. 

* If the data is a date, and you want to do range searches, choose DATE. 
In this tutorial, the elements and attributes are mapped to either 


ORDER_SIDE_TAB, PART_SIDE_TAB or, SHIP_SIDE_TAB. The tables below 
show which table each element or attribute is mapped to. 


ORDER_SIDE_TAB 


Column name Data type Location path Multiple 
occurring? 

ORDER_KEY INTEGER /Order/@key No 

CUSTOMER VARCHAR(16) /Order /Customer / Name No 


PART_SIDE_TAB 


Column name Data type Location path Multiple 
occurring? 
PRICE DECIMAL(10,2) /Order/Part/ExtendedPrice Yes 


SHIP_SIDE_TAB 


Column name Data type Location path Multiple 
occurring? 
DATE DATE /Order/Part/Shipment/ShipDate Yes 


Enabling the database: 


To store XML information in the database, you need to enable it for the XML 
Extender. When you enable a database for XML, the XML Extender: 


* Creates user-defined types (UDTs), user-defined functions (UDFs), and 
stored procedures. 
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* Creates and populates control tables with the necessary metadata that the 
XML Extender requires. 


* Creates the DB2XML schema and assigns the necessary privileges. 
To enable the database for XML: 


Use one of the following methods to enable the database. 
* Navigator: Enter the command: 

Run EnableDB.sql 
* OS command line: Enter: 

CALL PGM(QDBXM/QZXMADM) PARM(enable_db &RDBDatabase) 


Creating and populating the SALES_DB tables: 


To set up the lesson environment, create and populate the SALES_DB tables. 
These tables contain the tables described in the planning sections. 


To create the tables, use one of the following methods: 
* Navigator: Run: 

C_SalesDb.sql] 
* OS command line: Enter the following command: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(C_SALESDB) NAMING (*SQL) 


Enabling the XML column and storing the document: 


In this lesson, you will enable a column for XML Extender and store an XML 
document in the column. For these tasks, you will: 


1. Insert the DTD for the XML document into the DTD reference table, 
DTD_REF 


2. Prepare a DAD file that specifies the XML document location and side 
tables for structural search. 


3. Add a column in the SALES_TAB table with an XML user-defined type of 
XMLVARCHAR. 


4. Enable the column for XML. 
5. Index the side tables for structural search. 


6. Store the document using a user-defined function, which is provided by 
the XML Extender. 


Storing the DTD in the DTD repository: 


You can use a DTD to validate XML data in an XML column. The XML 
Extender creates a table in the XML-enabled database, called DTD_REF. The 
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table is known as the DTD reference and is available for you to store DTDs. 
When you validate XML documents, you must store the DTD in this 
repository. The tutorial DTD is in dxxsamples/dtd/getstart.dtd. 
* Navigator: Run 

InsertDTD. sql 
* OS command line: Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(INSERTDTD) NAMING(*SQL) 


Creating a DAD file for XML column: 


This section explains how you would create a DAD file for XML column. In 
the DAD file, you specify that the access and storage method your are using 
is XML column. It is here that you define the tables and columns for indexing. 


In the following steps, elements in the DAD are referred to as tags and the 
elements of your XML document structure are referred to as elements. A 
sample of a DAD file similar to the one you will create is in 
dxxsamples/dad/getstart_xcolumn.dad. It has some minor differences from 
the file generated in the following steps. If you use it for the lesson, the file 
paths might be different than for your environment; the <validation> value is 
set to NO, rather than YES. 


To create a DAD file for use with XML column: 
1. Open a text editor and name the file getstart_xcolumn.dad 
All the tags used in the DAD file are case sensitive. 
2. Create the DAD header, with the XML and the DOCTYPE declarations. 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM " /dxxsamples/dtd/dad.dtd"> 


The DAD file is an XML document and requires XML declarations. 

3. Insert opening and closing (<DAD> and</DAD> ) tags for the 
document. All other tags are located inside these tags. 

4. Insert opening and closing (<DTDID> and</DTDID>) tags with a DTD 
ID to specify a DTD if the document will be validated: 
<dtdid> dxxsamples/dtd/getstart.dtd</dtdid> 


Verify that this string matches the value used as the first parameter value 
when inserting the DTD in the DTD reference table. For example, the 
path you used for the DTDID might be different than the string 
mentioned above if you are working on a different machine drive. 

5. Insert opening and closing (<validation> and </validation>) tags and a 
keyword YES or NO to indicate whether you want the XML Extender to 
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validate the XML document structure using the DTD you inserted into 
the DTD repository table. For example: 


<validation>YES</validation> 


The value of <validation> must be in uppercase letters. 


6. Insert opening and closing (<Xcolumn> and</Xcolumn>) tags to specify 
that the storage method is XML column. 


7. Create side tables. For each side table that you want to create: 


a. Insert opening and closing (<table> and </table>) tags for each side 
table that is to be generated, specifying the name of the side table in 
quotation marks using the “name” attribute as indicated here: 
<Xcolumn> 
<table name="order_side_tab"> 
</table> 
<table name="part_side_tab"> 
</table> 
<table name="ship_side_tab"> 
</table> 
</Xcolumn> 

b. Inside the table tags, insert a <column> tag for each column that you 
want the side table to contain. Each column has four attributes: name, 
type, path and, multi_occurrence. 


Example: 


<table name="person_names">> 
<column name ="fname" 
type="varchar (50) " 
path="/person/firstName" 
multi_occurrence="NO0"/> 
<column name ="]name" 
type="varchar (50) " 
path="/person/lastName" 
multi_occurrence="NO0"/> 
</table> 


Where: 


Name 
Specifies the name of the column that is created in the side 
table. 


Type Indicates the data type in the side table for each indexed 
element or attribute. 


Path Specifies the location path in the XML document for each 
element or attribute to be indexed. 


Multi_occurrence 
Indicates whether the element or attribute referred to by the 
path attribute can occur more than once in the XML 
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document. The possible values for multi_occurrence are YES or 
NO. If the value is NO, then you can mention more than one 
column tag in the side table. If the value is YES, you can 
mention only one column in the side table. 


<Xcolumn> 
<table name="order_side_tab"> 
<column name="order_key" 
type="integer" 
path="/Order/@key" 
multi_occurrence="N0"/> 
<column name="customer" 
type="varchar (50) " 
path="/Order/Customer/Name" 
multi_occurrence="N0"/> 
</table> 
<table name="part_side_tab"> 
<column name="price" 
type="decimal (10,2)" 
path="/Order/Part/ExtendedPrice" 
multi_occurrence="YES"/> 
</table> 
<table name="ship_side_tab"> 
<column name="date" 
type="DATE" 
path="/Order/Part/Shipment/ShipDate" 
multi_occurrence="YES"/> 
</table> 
</Xcolumn> 


Ensure that you have a closing </Xcolumn> tag after the last </table> 
tag. 

Ensure that you have a closing </DAD> tag after the </Xcolumn> tag. 
Save the file with the following name: 

getstart_xcolumn.dad 


You can compare the file that you just created with the sample file, 
dxxsamples/dad/getstart_xcolumn.dad. This file is a working copy of the 
DAD file required to enable the XML column and create the side tables. The 
sample files contain references to files that use absolute path names. Check 
the sample files and change these values for your directory paths. 


Creating the SALES_TAB table: 


In this section you create the SALES_TAB table. Initially, it has two columns 
with the sale information for the order. 


To create the table: Enter the following CREATE TABLE statement using one 
of the following methods: 


* Navigator: Run C_SalesTab.sql 
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* OS command line: Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(C_SALESTAB) NAMING(*SQL) 


Adding the column of XML type: 


Add a new column to the SALES_TAB table. This column will contain the 
intact XML document that you generated earlier and must be of XML UDT. 
The XML Extender provides multiple data types. In this tutorial, you will 
store the document as XMLVARCHAR. 


To add the column of XML type: 


Run the SQL ALTER TABLE statement using one of the following methods: 
* Navigator: Run AddOrder.sql 
* OS command line: Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(ADDORDER) NAMING(*SQL) 


Enabling the XML column: 


After you create the column of XML type, you enable it for the XML Extender. 
When you enable the column, the XML Extender reads the DAD file and 
creates the side tables. Before enabling the column, you must: 


* Determine whether you want to create a default view of the XML column, 
which contains the XML document joined with the side-table columns. You 
can specify the default view when querying the XML document. In this 
lesson, you will specify a view with the -v parameter. 


* Determine whether you want to specify a primary key as the ROOT ID, the 
column name of the primary key in the application table and a unique 
identifier that associates all side tables with the application table. If you do 
not specify a primary key, the XML Extender adds the DXXROOT_ID 
column to the application table and to the side tables. 

The ROOT_ID column is used as key to tie the application and side tables 
together, allowing the XML Extender to automatically update the side tables 
if the XML document is updated. In this lesson, you will specify the name 
of the primary key in the command (INVOICE_NUM) with the -r 
parameter. The XML Extender will then use the specified column as the 
ROOT_ID and add the column to the side tables. 

* Determine whether you want to specify a table space or use the default 
table space. In this lesson, you will use the default table space. 


To enable the column for XML: 


18 Administration and Programming for iSeries 


Run the dxxadm enable_column command, using one of the following 
methods: 


* Navigator: 
Run EnableCol.sql 
* OS command line: Enter: 


CALL QDBXM/QZXMADM PARM(enable_column dbname 
Sales _Tab Order 
'/dxxsamples/dad/getstart_xcolumn.dad' '-v' 
sales order_view '-r' invoice_num) 


Where dbname is the name of your RDB database. 


The XML Extender creates the side tables with the INVOICE_NUM column 
and creates the default view. 


Important: Do not modify the side tables in any way. Updates to the side 
tables should only be made through updates to the XML document itself. The 
XML Extender will automatically update the side tables when you update the 
XML document in the XML column. 


Viewing the column and side tables: 


When you enabled the XML column, you created a view of the XML column 
and side tables. You can use this view when working with the XML column. 


To view the XML column and side-table columns: 


Submit the following SQL SELECT statement from the DB2 command line: 
SELECT * FROM SALES _ORDER_VIEW 


The view shows the columns in the side tables, as specified in the 
getstart_xcolumn.dad file. 


Indexing side tables for structural search: 


Creating indexes on side tables allows you to do fast structural searches of the 
XML document. In this section, you create indexes on key columns in the side 
tables that were created when you enabled the XML column, ORDER. The 
service department has specified which columns their employees are likely to 
query most often.|Table 4] describes these columns, which you will index: 

Table 4. Side-table columns to be indexed 

Column Side table 


ORDER_KEY ORDER_SIDE_TAB 
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Table 4. Side-table columns to be indexed (continued) 


Column Side table 
CUSTOMER ORDER_SIDE_TAB 
PRICE PART_SIDE_TAB 
DATE SHIP_SIDE_TAB 


To index the side tables: 


Run the following CREATE INDEX SQL commands using one of the 
following methods: 

* Navigator: Run C_Index.sql 

* OS command line: Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(C_INDEX) NAMING (*SQL) 


Command line: 
Storing the XML document: 


Now that you have enabled a column that can contain the XML document 
and indexed the side tables, you can store the document using the functions 
that the XML Extender provides. When storing data in an XML column, you 
either use default casting functions or the XML Extender UDFs. Because you 
will be storing an object of the base type VARCHAR in a column of the XML 
UDT XMLVARCHAR, you will use the default casting function. 


To store the XML document: 


1. Open the XML document dxxsamples/xml/getstart. xml 
dxxsample/xml/getstart.xmldxxsamples/xml/getstart.xml. Ensure that the 
file path in the DOCTYPE matches the DTD ID specified in the DAD and 
when inserting the DTD in the DTD repository. You can verify they match 
by querying the DB2XML.DTD_REF table and by checking the DTDID 
element in the DAD file. If you are using a different drive and directory 
structure than the default, you might need to change the path in the 
DOCTYPE declaration. 

2. Run the SQL INSERT command, using one of the following methods: 

* Navigator: Run InsertXML.sql 
* OS command line: Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR (INSERTXML) NAMING (*SQL) 
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To verify that the tables have been updated, run the following SELECT 
statements for the tables from the command line. 


SELECT * FROM SALES TAB 


+ 


SELECT 


+ 


FROM PART_SIDE_TAB 
SELECT * FROM ORDER_SIDE_TAB 


SELECT 


+ 


FROM SHIP_SIDE_TAB 
Searching the XML document: 


You can search the XML document with a direct query against the side tables. 
In this step, you will search for all orders that have a price over 2500.00. 


To query the side tables: 


Run the SQL SELECT statement, using one of the following methods: 
* Navigator: Run QueryCol.sql 
* DB2 command line: 

Enter: 


select distinct sales_person from schema.sales_tab S, 
part_side_tab P where price > 2500.00 
and S.invoice_num = P.invoice_num; 


The result set should show the names of the salespeople who sold an item 
that had a price greater than 2500.00. 


You have completed the getting started tutorial for storing XML documents in 
DB2 tables. 


Related concepts: 


* (Introduction to XML Extender” on page 3 


* “Lesson: Composing an XML document” on page 21 


* {Getting Started with XML Extender” on page 8 


Lesson: Composing an XML document 


This lesson teaches you how to compose an XML document from existing 
DB2® data. 


The Scenario: 


You have been given the task of taking information in an existing purchase 
order database, SALES_DB, and extracting requested information from it to be 
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stored in XML documents. The service department will then use these XML 
documents when working with customer requests and complaints. The service 
department has requested specific data to be included and has provided a 
recommended structure for the XML documents. 


Using existing data, you will compose an XML document, getstart.xml, from 
data in these tables. 


You will also plan and create a DAD file that maps columns from the related 
tables to an XML document structure that provides a purchase order record. 
Because this document is composed from multiple tables, you will create an 
XML collection, associating these tables with an XML structure and a DTD. 
You use this DTD to define the structure of the XML document. You can also 
use it to validate the composed XML document in your applications. 


The existing database data for the XML document is described in the 
following tables. The column names in italics are columns that the service 
department has requested in the XML document structure. 


ORDER_TAB 

Column name Data type 
ORDER_KEY INTEGER 
CUSTOMER VARCHAR(16) 
CUSTOMER_NAME VARCHAR(16) 
CUSTOMER_EMAIL VARCHAR(16) 
PART_TAB 

Column name Data type 
PART_KEY INTEGER 
COLOR CHAR(6) 
QUANTITY INTEGER 
PRICE DECIMAL(10,2) 
TAX REAL 
ORDER_KEY INTEGER 
SHIP_TAB 

Column name Data type 
DATE DATE 

MODE CHAR(6) 
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Column name Data type 
COMMENT VARCHAR(128) 
PART_KEY INTEGER 
Planning: 


Before you begin working with the XML Extender to compose your 
documents, you need to determine the structure of the XML document and 
how it corresponds to the structure of your database data. This section will 
provide an overview of the XML document structure that the service 
department has requested, of the DTD you will use to define the structure of 
the XML document, and how this document maps to the columns that contain 
the data used to populate the documents. 


Determining the document structure: 


The XML document structure takes information for a specific order from 
multiple tables and creates an XML document for the order. These tables each 
contain related information about the order and can be joined on their key 
columns. The service department wants a document that is structured by the 
order number as the top level, and then customer, part, and shipping 
information. They want the document structure to be intuitive and flexible, 
with the elements describing the data, rather than the structure of the 
document. (For example, the customer’s name should be in an element called 
“customer,” rather than a paragraph.) Based on their request, the hierarchical 
structure of the DTD and the XML document should be like the one described 


in |Figure 2 on page 24 
After you have designed the document structure, you should create a DTD to 


describe the structure of the XML document. This tutorial provides an XML 
document and a DTD for you. Using the rules of the DTD, and the 


hierarchical structure of the XML document, you can map a hierarchical map 
of your data, as shown in |Figure 2 on page 24 
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DTD Raw data 


<?xml encoding="ibm-1047"?> <?xml version="1.0"?> 
<!ELEMENT Order (Customer, Part+)> <!DOCTYPE Order SYSTEM 
<!ATTLIST Order key CDATA #REQUIRED> "dxx_install samples/dtd/getstart.dtd"> 
<!ELEMENT Customer (Name, Email)> <Order key="1"> 
<!ELEMENT Name (#PCDATA)> <Customer> 
<!ELEMENT Email (#PCDATA)> <Name>American Motors</Name> 
<!ELEMENT Part (key,Quantity,ExtendedPrice, Tax, Shipment+)> <Email>parts@am.com</Email> 
<!ELEMENT key (#PCDATA)> = </Customer> 
<!ELEMENT Quantity (#PCDATA)> <Part color="black "> 
<!ELEMENT ExtendedPrice (#PCDATA)> <key>68</key> 
<!ELEMENT Tax (#PCDATA)> <Quantity>36</Quantity> 
<!ATTLIST Part color CDATA #REQUIRED> <ExtendedPrice>34850.16</ExtendedPrice> 
<!ELEMENT Shipment (ShipDate, ShipMode)> <Tax>6.000000e-02</Tax> 
<!ELEMENT ShipDate (#PCDATA)> : 
<!ELEMENT ShipMode (#PCDATA)> </Part> 

</Order> 

Order 


<key > Customer Part 


Name Email 


(American Motors) (parts@am.com ) 


Key Quantity ExtendedPrice Tax Shipment 
Colack)) (C68) (36) (3485016 ) (002) 


ShipDate ShipMode 


(4998-08-19) (Boat _) 


<> -Attribute =Element C _)=value 


Figure 2. The hierarchical structure of the DTD and XML document 


Mapping the XML document and database relationship: 


After you have designed the structure and created the DTD, you need to 
show how the structure of the document relates to the DB2 tables that you 


will use to populate the elements and attributes. You can map the hierarchical 
structure to specific columns in the relational tables, as in|Figure 3 on page 25 
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root_node 


element_node 
Order 


attripute_node element_node element_node 
Key Customer Part 
order_key 
element_node element_node 
Name Email 
text_node text_node 


customer_name| | customer_email 


attribute node element_node element_node 
Color Quantity Tax 
color text_node text_node 
element_node quantity | | element_node tax | |element_node 
Key ExtendedPrice Shipment 
text_node text_node 
part_key price 


element_node| |element_node 


ShipDate ShipMode 
text_node text_node 
Names of columns in DB2 tables gals ns 


Figure 3. XML document mapped to relational table columns 


This figure uses nodes to identify elements, attributes, and text within the 
XML document structure. These nodes are used in the DAD file and are 
explained more fully in later steps. 


Use this relationship description to create DAD files that define the 
relationship between the relational data and the XML document structure. 


In this tutorial, you will be creating a DAD file for the XML collection used to 
compose the document. The XML collection DAD file maps the tables with 
existing data to the XML document structure. 


To create the XML collection DAD file, you need to understand how the XML 


document corresponds to the database structure, as described in so 
that you can describe from what tables and columns the XML document 
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structure derives data for elements and attributes. You will use this 
information to create the DAD file for the XML collection. 


Getting started scripts and samples: 


For this tutorial, we provide a set of scripts for you to use to set up your 
environment. The OS command line scripts are in the dxxsamples library. The 
Navigator SQL Script Files are in the /dxxsamples directory. 


Table 5}lists the samples that are provided to complete the getting started 
tasks. 


Table 5. List of the XML collection lesson samples 


Lesson description OS command line scripts | Navigator SQL Script File 
Create and fill SALES DB C_SALESDB C_SalesDb.sql 

tables 

Composes an XML Manual command Genxml_sql.sql 


document and returns it to 
a result table 


Removes sample tables and |D_SALESDB and CleanupCllec.sql 
disables column CLEANUPCOL 


Setting up the lesson environment: 


If you have already completed the first lesson "Store an XML document in an 
XML column, skip this section. In this section, you: 


* Enable the database. 
* Create and populate the tables used for the lessons. 


Enabling the database: 


To store XML information in the database, you need to enable it for the XML 
Extender. When you enable a database for XML, the XML Extender: 


* Creates the user-defined types (UDTs), user-defined functions (UDFs), and 
stored procedures. 


* Creates and populates control tables with the necessary metadata that the 
XML Extender requires. 


* Creates the DB2XML schema and assigns the necessary privileges. 


Important: If you have completed the XML column lesson and have not 
cleaned up your environment, you might be able skip this step. 


To enable the database for XML: Use one of the following methods. 
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* Navigator: Enter the command: 


CALL &Schema.QZXMADM('enable_db',' 
&DBNAME') ; 


¢ OS command line: Enter: 


CALL PGM(QDBXM.QZXMADM) PARM(enable_db 
&RDBDatabase) 


Creating and populating the SALES_DB tables: 


To set up the lesson environment, create the populate the SALES_DB tables. 
These tables contain the tables described in the planning sections. 


To create the tables: 
* Navigator: Run C_SalesDb.sql 
* (iSeries) OS command line: Enter the following command: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(C_SALESDB) NAMING (*SQL) 


Creating the XML collection: preparing the DAD file: 


Because the data already exists in multiple tables, you will create an XML 
collection, which associates the tables with the XML document. To create an 
XML collection, you define the collection by preparing a DAD file. 


In this section, you create the mapping scheme in the DAD file that specifies 
the relationship between the tables and the structure of the XML document. 


In the following steps, elements in the DAD are referred to as tags and the 
elements of your XML document structure are referred to as elements. A 
sample of a DAD file similar to the one you will create is in dxx_install 
dxxsamples/dad/getstart_xcollection.dad. 


It has some minor differences from the file generated in the following steps. If 
you use it for the lesson, note that the file paths might be different than in 
your environment and you might need to update the sample file. 


To create the DAD file for composing an XML document: 


1. From the dxxsamples/xm1 directory, open a text editor and create a file 
called getstart_xcollection.dad. 


2. Create the DAD header, using the following text: 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "/dxxsamples/dtd/dad.dtd"> 


3. Insert the <DAD></DAD> tags. All other tags are located inside these 
tags. 
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4. Specify <validation> </validation> tags to indicate whether the XML 
Extender validates the XML document structure when you insert a DTD 
into the DTD repository table. This lesson does not require a DTD and 
the value is NO. 


<validation>N0</validation> 


The value of the <validation> tags must be uppercase. 


5. Use the <Xcollection></Xcollection> tags to define the access and storage 
method as XML collection. The access and storage methods define that 
the XML data is stored in a collection of DB2 tables. 
<Xcollection> 
</Xcollection> 

6. After the <Xcollection> tag, provide an SQL statement to specify the 
tables and columns used for the XML collection. This method is called 
SQL mapping and is one of two ways to map relational data to the XML 
document structure. Enter the following statement: 
<Xcollection 
<SQL_stmt> 

SELECT o.order_key, customer_name, customer_email, p.part_key, color, 
quantity, price, tax, ship_id, date, mode from order_tab 0, part_tab p, 
(select db2xml.generate_unique() 
as ship_id, date, mode, part_key from ship tab) as s 
WHERE o.order_key = 1 and 
p-price > 20000 and 
p.order_key = o.order_key and 
s.part_key = p.part_key 
ORDER BY order_key, part_key, ship_id 
</SQL_stmt> 
</Xcollection> 


This SQL statement_uses the following guidelines when using SQL 

mapping. Refer to|Figure 3 on page 25|for the document structure. 

* Columns are specified in top-down order, by the hierarchy of the XML 
document structure. For example, the columns for the order and 


customer elements are first, the part element are second, and the 
shipment are third. 


* The columns for a repeating section, or non-repeating section, of the 
template that requires data from the database are grouped together. 
Each group has an object ID column: ORDER_KEY, PART_KEY, and 
SHIP_ID. 


* The object ID column is the first column in each group. For example, 
O.ORDER_KEY precedes the columns related to the key attribute and 
p-PART_KEY precedes the columns for the Part element. 

* The SHIP_TAB table does not have a single key conditional column, 
and therefore, the generate_unique user-defined function is used to 
generate the SHIP_ID column. 
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* The object ID columns are then listed in top-down order in an ORDER 
BY statements. The columns in ORDER BY should not be qualified by 
any schema and table name and should match the column names in 
the SELECT clause. 


Add the following prolog information to be used in the composed XML 
document: 


<prolog>?xml version="1.0"?</prolog> 


This exact text is required for all DAD files. 


Add the <doctype></doctype> tags to be used in the XML document 
you are composing. The <doctype> tag contains the path to the DTD 
stored on the client. 

<doctype>!DOCTYPE Order SYSTEM 
"/dxxsamples/dtd/getstart.dtd"</doctype> 

Define the root element of the XML document using the 
<root_node></root_node> tags. Inside the root_node, you specify the 
elements and attributes that make up the XML document. 


Map the XML document structure to the DB2 relational table structure 
using the following three types of nodes: 


element_node 
Specifies the element in the XML document. Element_nodes can 
have child element_nodes. 


attribute_node 
Specifies the attribute of an element in the XML document. 


text_node 
Specifies the text content of the element and the column data in a 
relational table for bottom-level element_nodes. 


Figure 3 on page 25|shows the hierarchical structure of the XML 


document and the DB2 table columns, and indicates what kinds of nodes 
are used. The shaded boxes indicate the DB2 table column names from 
which the data will be extracted to compose the XML document. 


The following steps have you add each type of node, one type at a time. 


a. Define an <element_node> tag for each element in the XML 
document. 


<root_node> 
<element_node name="O0rder"> 
<element_node name="Customer"> 
<element_node name="Name"> 
</element_node> 
<element_node name="Email"> 
</element_node> 
</element_node> 
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<element_node name="Part"> 
<element_node name="key"> 
</element_node> 
<element_node name="Quantity"> 
</element_node> 
<element_node name="ExtendedPrice"> 
</element_node> 
<element_node name="Tax"> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 
</element_node> 
<element_node name="ShipMode"> 
</element_node> 
</element_node> <!-- end Shipment --> 
</element_node> <!-- end Part --> 
</element_node> <!-- end Order --> 
</root_node> 


Note that the <Shipment> child element has an attribute of 
multi_occurrence=YES. This attribute is used for elements without an 
attribute, that are repeated in the document. The <Part> element does 
not use the multi-occurrence attribute because it has an attribute of 
color, which makes it unique. 


b. Define an <attribute_node> tag for each attribute in your XML 
document. These attributes are nested in their element_node. The 
added attribute_nodes are highlighted in bold: 


<root_node> 
<element_node name="Order"> 
<attribute_node name="key"> 
</attribute_node> 
<element_node name="Customer"> 
<element_node name="Name"> 
</element_node> 
<element_node names"Emai1"> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="color"> 
</attribute_node> 
<element_node name="key"> 
</element_node> 
<element_node name="Quantity"> 
</element_node> 


</element_node> <!-- end Part --> 
</element_node> <!-- end Order --> 
</root_node> 


30 } =Administration and Programming for iSeries 


c. For each bottom-level element_node, define <text_node> tags, 
indicating that the XML element contains character data to be 
extracted from DB2 when composing the document. 


<root_node> 
<element_node name="0rder"> 
<attribute_node name="key"> 
</attribute_node> 
<element_node name="Customer"> 
<element_node name="Name"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="Email"> 
<text_node> 
</text_node> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="color"> 
</attribute_node> 
<element_node name="key"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="Quantity"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="ExtendedPrice"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="Tax"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 
<text_node> 
</text_node> 
</element_node> 
<element_node name="ShipMode"> 
<text_node> 
</text_node> 
</element_node> 
</element_node> <!-- end Shipment --> 
</element_node> <!-- end Part --> 
</element_node> <!-- end Order --> 
</root_node> 


d. For each bottom-level element_node, define a <column/> tag. These 
tags specify from which column to extract data when composing the 
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XML document and are typically inside the <attribute_node> or the 
<text_node> tags. Remember, the columns defined here must be in 
the <SQL_stmt> SELECT clause. 


<root_node> 
<element_node name="Order"> 
<attribute_node name="key"> 
<column name="order_key"/> 
</attribute_node> 
<element_node name="Customer"> 
<element_node name="Name"> 
<text_node> 
<column name="customer_name"/> 
</text_node> 
</element_node> 
<element_node name="Email"> 
<text_node> 
<column name="customer_email"/> 
</text_node> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="color"> 
<column name="color"/> 
</attribute_node> 
<element_node name="key"> 
<text_node> 
<column name="part_key"/> 
</text_node> 
<element_node name="Quantity"> 
<text_node> 
<column name="quantity"/> 
</text_node> 
</element_node> 
<element_node name="ExtendedPrice"> 
<text_node> 
<column name="price"/> 
</text_node> 
</element_node> 
<element_node name="Tax"> 
<text_node> 
<column name="tax"/> 
</text_node> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 
<text_node> 
<column name="date"/> 
</text_node> 
</element_node> 
<element_node name="ShipMode"> 
<text_node> 
<column name="mode"/> 
</text_node> 
</element_node> 
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</element_node> <!-- end Shipment --> 
</element_node> <!-- end Part --> 
</element_node> <!-- end Order --> 
</root_node> 
11. Ensure that you have an ending </root_node> tag after the last 
</element_node> tag. 


12. Ensure that you have an ending </Xcollection> tag after the 
</root_node> tag. 

13. Ensure that you have an ending </DAD> tag after the </Xcollection> 
tag. 

14. Save the file as getstart_xcollection.dad 


You can compare the file you have just created with the sample file dxx_install 
dxxsamples/dad/getstart_xcollection.dad. This file is a working copy of the 
DAD file required to compose the XML document. The sample file contains 
location paths and file path names that might need to be changed to match 
your environment in order to be run successfully. 


In your application, if you will use an XML collection frequently to compose 
documents, you can define a collection name by enabling the collection. 
Enabling the collection registers it in the XML_USAGE table and helps 
improve performance when you specify the collection name (rather than the 
DAD file name) when running store procedures. In these lessons, you will not 
enable the collection. 


Composing the XML document: 


In this step, you use the dxxGenXML() stored procedure to compose the XML 
document specified by the DAD file. This stored procedure returns the 
document as an XMLVARCHAR UDT. 


To compose the XML document: 


Use one of the following methods: 
* Navigator: Run Genxml_sql.sql 
* OS command line: Enter: 


CALL DXXSAMPLES/GENX PARM(dbName ' /dxxsamples 
/dad/getstart_xcollection.dad' result_tab doc ' ') 


Tip: This lesson teaches you how to generate one or more composed XML 
documents using DB2 stored procedure’s result set feature. Using a result set 
allows you to fetch multiple rows to generate more than one document. As 
you generate each document, you can export it to a file. This method is the 
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simplest way to demonstrate using result sets. For more efficient ways of 
fetching data see the CLI examples in the DXXSAMPLES/QCSRC source 
filedxx_install. 


Transforming an XML document into an HTML file: 


To show the data from the XML document in a browser, you must transform 
the XML document into an HTML file by using a stylesheet and the 
XSLIransformToFile function. Use the following steps to transform to an 
HTML file: 


1. Generate a stylesheet: 


<?xml version="1.0" encoding="UTF-8"?> 
<xsl:stylesheet version="1.0" 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 


<xs]:template match="/"> 
<html> 
<head/> 
<body> 


</body> 
</htm1> 
</xsl:template> 
</xsl:stylesheet> 


2. For each element, create a tag using the following format: 


<xsl:for-each select="Xxxxxx"> 


This tag will be used for transforming instructions. Create a tag for each 
element of the hierarchy of the XML document. For example: 


<?xml version="1.0" encoding="UTF-8"?> 
<xsl:stylesheet version="1.0" 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 


<xsl:template match="/"> 
<html> 
<head/> 
<body> 


<xs1:for-each select="O0rder"> 


<xsl:for-each select="Customer"> 
<xsl:for-each select="Name | Email"> 
</xs1:for-each> 
</xs1:for-each> 
<xsl:for-each select="Part"> 
<xs]:for-each select="key | Quantity | ExtendedPrice | Tax"> 
</xs1:for-each> 
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<xsl:for-each select="Shipment"> 
<xsl:for-each select="ShipDate | ShipMode"> 
</xs1:for-each> 
</xs1: for-each> 
</xs1:for-each> 
</xs1:for-each> 
</body> 
</htm1> 
</xsl:template> 
</xsl:stylesheet> 


To format the HTML file, use a simple list that shows the hierarchy of the 


XML elements to make the data more readable. Create some additional 
text elements to describe the data. For example, your HTML mark-up 
might look like this: 


<?xml version="1.0" encoding="UTF-8"?> 
<xsl:stylesheet version="1.0" 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 


<xsl:template match="/"> 
<html> 
<head/> 
<body> 


<ol style="list-style:decimal outside"> 
<xsl:for-each select="Order"> 
<li> Orderkey : <xsl:value-of-select="@key"/ <br/> 


<xsl:for-each select="Customer"> 
<b>Customer</b><br/> 
<xsl:for-each select="Name | Email"> 
<xsl:value-of select="name()"/> 
<xsl:text> : </xs]:text> 
<xsl:value-of select="."/> 
<xs]:text>, </xsl:text> 
</xs1:for-each> 
</xs1:for-each> 


<br/><br/> 
<ol type="A"> 
<xsl:for-each select="Part"> 
<1i><b>Parts</b><br/> 
Color : <xsl:value-of select="@color"/> 
<xs]:text>, </xsl:text> 


<xs1:for-each select="key | Quantity | ExtendedPrice | Tax"> 
<xsl:value-of select="name()"/> 
<xsl:text> : </xsl:text> 
<xsl:value-of select="."/> 
<xsl:text>, </xs]l:text> 
</xs1:for-each> 


<br/><br/> 


<ol type="a"> 
<xsl:for-each select="Shipment"> 
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<1 i><b>Shi pment</b><br/> 
<xsl:for-each select="ShipDate | ShipMode"> 
<xsl:value-of select="name()"/> 
<xs]l:text> : </xsl:text> 
<xsl:value-of select="."/> 
<xsl:text>, </xsl:text> 
</xs1:for-each> 
</li> 
</xs1:for-each> 
</ol><br/> 
</li> 
</xs1:for-each> 
</ol> 
</li> 
</xs1:for-each> 
</ol> 
</body> 
</html> 
</xsl:template> 
</xsl:stylesheet> 


4. Use Xpath to edit the <xsl:value-of select="xxx"> tags with data from the 
XML document. 


The element tags are <xsl:value-of select”.">, where the period (".") is used 
to get data from normal elements. 


The attribute tags are <xsl:value-of select="@attributname"> , where the 
ampersand (@ ) that is added by the attribute name will extract the value 
of the attribute. You can use the <xsl:value-of select="name()"> to get the 
name of the XML tag. 


<?xml version="1.0" encoding="UTF-8"?> 
<xsl:stylesheet version="1.0" 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 


<xsl:template match="/"> 
<html> 
<head/> 
<body> 


<ol style="list-style:decimal outside"> 
<xsl:for-each select="Order"> 
<li> Orderkey : <xsl:value-of-select="@key"/ <br/> 


<xsl:for-each select="Customer"> 
<b>Customer</b><br/> 
<xs]:for-each select="Name | Email"> 
<xsl:value-of select="name()"/> 
<xs]:text> : </xs]:text> 
<xsl:value-of select="."/> 
<xs]:text>, </xsl:text> 
</xs1:for-each> 
</xs1:for-each> 


<br/><br/> 
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<ol type="A"> 
<xsl:for-each select="Part"> 
<]i><b>Parts</b><br/> 
Color : <xsl:value-of select="@color"/> 
<xs]:text>, </xsl:text> 


<xs1:for-each select="key | Quantity | ExtendedPrice | Tax"> 
<xsl:value-of select="name()"/> 
<xsl:text> : </xsl:text> 
<xsl:value-of select="."/> 
<xsl:text>, </xs]l:text> 
</xs1:for-each> 


<br/><br/> 
<ol type="a"> 
<xsl:for-each select="Shipment"> 
<1] i><b>Shi pment</b><br/> 
<xsl:for-each select="ShipDate | Shi pMode"> 
<xsl:value-of select="name()"/> 
<xs]:text> : </xsl:text> 
<xsl:value-of select="."/> 
<xs]:text>, </xsl:text> 
</xs1:for-each> 
</li> 
</xs1:for-each> 
</ol><br/> 
</li> 
</xs1:for-each> 
</ol> 
</li> 
</xs1:for-each> 
</ol> 
</body> 
</htm|> 
</xs1:template> 
</xsl:stylesheet> 


5. Create the HTML file in one of the following ways: 
* Use the XSLTransformToFile UDF: 


SELECT XSLTransformFile( CAST(doc AS CLOB(4k)), 
‘dxx_install\samples\xslt\getstart.xsl', 
'dxx_install\samples\html\getstart.html ') 
FROM RESULT_TAB 


* Use the following command: 
Getstart_xs]t.cmd 


The output file can only be written to a file system that is accessible to the 
DB2 server. 


Cleaning up the tutorial environment: 


If you want to clean up the tutorial environment, you can run one of the 
provided scripts or enter the commands from the command line to: 
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* Disable the XML column, ORDER 
* Drop tables created in the tutorial 
* Delete the DTD from the DTD reference table 


They do not disable or drop the SALES_DB database; the database is still 
available for use with XML Extender. You might receive error messages if you 
have not completed both lessons in this chapter. You can ignore these errors. 


To clean up the tutorial environment: 
Run the cleanup command files, using one of the following methods: 


Navigator: 
* To clean up the XML column environment, run CleanupCol.sql 
* To clean up the XML collection environment, run CleanupCllec.sql 


OS command line: 
* To clean up the XML column environment: 
1. Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(D_SALESDB) NAMING(*SQL) 


ho 


Enter: 


CALL PGM(QDBXM/QZXMADM) 
PARM(disable_column &DBNAME Sales Tab Order) 


Enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(CLEANUPCOL) NAMING(*SQL) 


* To clean up the XML collection environment, enter: 


RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) 
SRCMBR(D_SALESDB) NAMING (*SQL) 


o 


Related concepts: 
* |“Introduction to XML Extender” on page 3 


* |“Lesson: Storing an XML document in an XML column” on page 10 
* {Getting Started with XML Extender” on page 8 
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Part 2. Administration 


This part describes how to perform administration tasks for the XML 
Extender. 
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Administration Tools 


The XML Extender administration tools help you enable your database and 
table columns for XML, and map XML data to DB2® relational structures. The 
XML Extender provides the following administration tools for your use, 
depending on how you want to complete your administration tasks. 


Administration—details 


The XML operating environment on iSeries 
The following sections describe the XML operating environment for iSeries. 


Application programming 

All the XML Extender facilities supplied for application programs run in the 
iSeries environment as stored procedures or user-defined functions (UDFs). 
Some of the UDFs that refer to the XML file data type, require access to an IFS 
system. The DB2 XML trace file, is also written to an IFS file. 


Two C header files are provided for developing XML Extender applications. 
These files contain useful constants for calling the stored procedures and for 
the definitions of error codes. The header files are available in the following 
directories, after installation of the product: 


* /qibm/proddata/db2extenders/xml/include/dxx.h 
* /qibm/proddata/db2extenders/xml/include/dxxrc.h 


To develop C++ applications with these headers, use the 
INCDIR('/qibm/proddata/db2extenders/xml/include') option on the 
CRTCPPMOD iSeries command. 


When the sample programs have been restored from the save files, these 
header files are also available as physical file members in 
DXXSAMPLES/H(DXX) and DXXSAMPLES/H(DXXRC). To use these header 
files, the DXXSAMPLES library must be in your library list. 


Administration environment 
When performing administration tasks in the iSeries environment, you use the 


XML Extender administration wizard, the Qshell, the Navigator, or the native 
operating system (OS) command line. 
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Administration wizard 
You can use either an administration wizard from Windows or UNIX 
client, or an iSeries environment to complete administration tasks. 


Qshell 
You can run the administration command, dxxadm, and its options, in 
the Qshell. The administration command is described in [Chapter 6 
and provide 
options for managing XML column, XML collection, and databases for 
the XML Extender. 


Navigator 
You can call administration stored procedures in the Navigator. The 
administration stored procedures are described in /XML Extender 
and provide options 


for managing XML column, XML collection, and databases for the 
XML Extender. 


OS command line 
You can run the administration program, QZXMADM, from the OS 


command line. This program uses the administration command 
parameters described in|Chapter 6, “The dxxadm administration 
command” on page 149} and provide options for managing XML 
column, XML collection, and databases for the XML Extender. 

The following table summarizes the administration environment for the XML 


Extender. 


Table 6. XML Extender stored procedures and commands 


Environment Qshell Navigator OS command line 

Sample files DAD, DTD, and XML files DAD, DTD, and XML files DAD, DTD, and XML files are 
are stored under the are stored under the stored under the dxxsamples 
dxxsamples directory. dxxsamples directory. directory. 
° dxxsamples/dtd/dad.dtd + dxxsamples/getstart.exe * dxxsamples/dtd/dad.dtd 
* dxxsamples/dtd/*.* ° dxxsamples/dtd/dad.dtd * dxxsamples/dtd/*.* 
* dxxsamples/dad/*.* ° dxxsamples/dtd/*.* * dxxsamples/dad/*.* 
* dxxsamples/xml/*.* ° dxxsamples/dad/*.* ° dxxsamples/xml/*.* 


* dxxsamples/xml/*.* 


Program DXXSAMPLES library, DXXSAMPLES library on DXXSAMPLES library: 

executable which is pointed to by iSeries; no executables on * Sample SQL scripts in the 

files symbolic links in Windows or UNIX. SQLSTMT file 
dxxsamples /*. 


* Sample CL source in the 
QCLSRC file 


* Sample C++ source in the 
QCSEC file 
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Table 6. XML Extender stored procedures and commands (continued) 


Environment Qshell Navigator OS command line 
Command None * SOL files in DXXSAMPLES/SQLSTMT 
scripts path / DXXSAMPLES 


Preparing to administer the XML Extender 


This section describes the requirements for setting up and planning for XML 
Extender administration. 


To run XML Extender, you will need to install the following software. 


Required software for iSeries: 

* DB2 Universal Database’ Version 5 Release 2 

* iSeries'” International components for unicode (option 39 of 5722SS1) QICU 

* iSeries System Openness Includes (option 13 of 5722551) QSYSINC 

* iSeries Portable App Solutions Environment (option 33 of 5722551) QPASE 
(needed for compiles) 

* WebSphere® Development ToolSet (option 51 of 5722WDS) 51-54 ILE-C 
family 


* You might also need 5722JV1 if you plan to develop applications that use 
Java’ or Web-based applications. 


Optional software: 


¢ For structural text search, the DB2 Universal Database XML Extender 
Version 7.2 - available with DB2 Universal Database (options 1 and 3 of 
5722DE1) 

¢ For the XML Extender administration wizard: 


— DB2 Universal Database Java Database Connectivity (JDBC) 


Migrating XML Extender from Version 7 to Version 7.2 
If you have been using XML Extender Version 7.1, you must migrate a 
database enabled for XML Extender before using an existing XML-enabled 
database with XML Extender Version 7.2. Also, because the XML column 
storage method has been enhanced for iSeries V5R2, each schema that 
contains columns enabled for XML in iSeries V5R1 must be migrated. 


Note: Before you install DB2 XML Extender Version 7 Release 2, apply all the 
Version 7 Release 1 PTFs and follow the migration instructions 


contained in the PTF cover letters. 


Procedure: 
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To automatically migrate an XML enabled database and XML enabled 
columns: 


1. Install DB2 XML Extender Version 7.2. 


2. Install the migration program available with PTF 5722DE1 V5R2MO0 
S105666. 


3. From the operating system command line, enter: 
CALL QDBXM/QZXMMIGV 


To manually migrate columns enabled for XML extender: 


1. Retrieve the DAD file that is used to enable a column from the 
DB2XML.XML_USAGE table before you disable any columns. 

2. Re-enable any databases that contain XML columns that had been 
previously enabled for XML Extender. 


a. 


e. 


Use SAVOBJ to save the data in the side tables. 


b. Disable the XML column. 
Cc. 
d. Use the RSTOBJ to restore the data to the side tables. If your side 


Enable the XML column. 


tables have long names, you must drop the side tables before you 
restore them. 


Recreate indexes. 


IASP considerations 


For an iSeries 


an IASP database for XML extender: 


* You can enable your *SYSBAS database or a database on an IASP for XML 


extender. 


* You may enable more than one IASP database for XML extender, but you 


can only have one active IASP database at a time. 


* If you have enabled the *SYSBAS database for XML extender, you will not 


be able to enable an IASP database. 


Migrating XML Extender data from SYSBAS to an IASP 
To move your XML data from SYSBAS to an IASP, detailed planning is 


required. 


Different Save/Restore steps will be required for: 

* XML collection database files 

* database files with XML user-defined types (UDTs) 
* XML column database files 
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system, an independent auxiliary storage pool ([ASP) device 
can be used as an external database. In DB2 XML Extender Version 7.2, this 
IASP can be enabled for XML Extender. Consider the following when enabling 


To migrate to an IASP: 


1. Save your XML data using the steps described in{“Saving and restoring] 
2. Disable all XML columns. 
3. Disable all XML collections. 


4. Drop all schemas that contain XML data (the data that you saved in step 
1.) 


. Drop all columns that were defined with XML Extender UDTs. 
. Disable the SYSBAS database for XML Extender. 
. Sign off. 


. Execute the SETASPGRP to the IASP group. 
. Enable the IASP database for XML Extender. 


. Restore your XML data using the directions in |Saving and restoring for 
XML columns and XML collections” 


Saving and restoring for XML columns and XML collections 
On the iSeries, save and restore procedures for schemas have the following 


restrictions: 


5 
6 
7 
8. Sign on. 
9 
0 
1 


* Do not save, restore, or delete the DB2XML schema (library). 
* The following conditions apply when you restore user-created schemas that 
contain database files used by XML Extender: 

— Schemas that contain XML collections, but do not contain XML-enabled 
columns, can be restored at the library level using SAVLIB and RSTLIB 
commands, provided the database on the new system has been enabled 
for XML Extender. If the XML collection was enabled on the old system, 
you must re-enable the XML collection on the new system. 

— Schemas that contain columns of XML user-defined types (KXMLCLOB, 
XMLVarchar, etc.) can be restored at the library level, provided that the 
column has not been enabled for XML and the database on the new 
system has been enabled for XML Extender. 

— Schemas that contain columns that have been enabled for XML cannot be 
restored at the library level. The base table and the side tables (database 
files) can be restored at the object level using the RSTOBJ command. 


The following procedures tell you how to restore schemas with database files 
that are used with XML collections and XML columns. 


To restore XML collection database files: 
1. Enable the database on the target system for XML Extender. 
2. Restore the XML collection database files using RSTLIB. 


Chapter 2. Administration 45 


3. If the XML collection was enabled on the original system, run the 
enable_collection command to enable the XML collection on the target 
system. 


To restore database files with XML user-defined types: 
1. Enable the database on the target system for XML Extender. 
2. Restore the database files using the RSTLIB command. 


To restore XML column database files: 
1. Enable the database on the target system for XML Extender. 
2. Restore the base table, using the RSTOBJ command. 


3. Remove any old triggers that were defined in the base table using the 
RMVPFTRG command. 


4. Enable the XML column on the target system. You must use the ’-r’ 
parameter to identify the primary key of the base table if the ’-r’ 
parameter was used to enable the base table on the previous system. 

5. Add user-defined triggers to the base table using the ADDPFTRG 
command, and restore those programs on the target system. 


6. Restore the data to the side tables using the RSTOBJ command. 


Restrictions: You cannot restore database files with RSTLIB when they 

contain XML-enabled columns for the following reasons: 

* Important metadata that is stored in the XML Extender is not restored to 
the new system when you restore your library and database files. This 
metadata can only be created on the target system by running the 
enable_column command. 

* When you restore your library with RSTLIB, SQL triggers in your library 
will be unusable because the prerequisite metadata will be missing from the 
XML Extender. The presence of these triggers will prevent you from 
running the enable_column command. 


Setting up XML Extender samples and the development environment for 
iSeries 
The following sections describe how to set up the administration 
environment, depending on the approach you plan to use for your application 


* For all environments -|“Unpack and restore sample files and getting started 
files” on page 47 


* For all environments -|“Creating an SQL collection (schema) for the 
samples” on page 48 


* For the administration environment of your choice: 


— When using the wizard -|Setting up the Wizard” on page 49 


46 Administration and Programming for iSeries 


— When using the Qshell command line - /‘Setting up the Qshell” on 
page 49 


— When using the Navigator - |“Setting up the iSeries Navigator interface” 


— When using the OS command line -|“Preparing the sample programs for 
the iSeries command line” on page 50 


* To run the getting started lessons - |Setting up the Getting Started 
environment for iSeries” on page 50 


Unpack and restore sample files and getting started files 
The samples are shipped as two iSeries Save File objects in the product 


directory. These files are: 


QDBXM/QZXMSAMP1 
Contains a SAVLIB save file for the DXXSAMPLES library. The library 
contains sample C and CL source code, C header files, and SQL 
statements for application development. 


QDBXM/QZXMSAMP2 
Contains a SAV save file of an IFS directory tree that will contain 


sample XML, DTD, and Data Access Definition (DAD) files, and a 
self-extracting GetStart.exe file to be used with the Navigator. 


The first step in preparing to use the administration environment is to have 
the iSeries administrator unpack and restore these save files to your system. 


The administrator should: 

* Unpack QDBXM/QZXMSAMP1 Save File to restore Samples source code 
and SETUP program to your system. 
From the OS command line, enter: 


RSTLIB SAVLIB(DXXSAMPLES) 
DEV (*SAVF) 
SAVF (QDBXM/QZXMSAMP1) 


The RSTLIB command unpacks the save file in the DXXSAMPLES library 
and it contains the objects listed in|Table 7 


Table 7. DXXSAMPLES library objects 


Object Type Attribute Description 

SETUP PGM CLP Compiles sample 
programs and Add 
IFS 

H FILE PF-SRC C Header files 

QCLSRC FILE PF-SRC Interface for 
Navigator 
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Table 7, DXXSAMPLES library objects (continued) 


Object Type Attribute Description 

QCSRC FILE PF-SRC Sample programs 

SOQLSTMT FILE PF-SRC SQL statements for 
samples 


* Unpack QDBXM/QZXMSAMP2 Save File to restore XML files and 
GetStart.exe to the user’s system. 


From the OS command line, enter: 


RST DEV('/qsys.1lib/qdbxm.1ib/qzxmsamp2.file') 
OBJ (('/QIBM/UserData/DB2Extenders/XML/Samples')) 


The RST DEV command restores the save file to the XML files to the IFS 
directory, /QIBM/UserData/DB2Extenders/XML/Samples. 


A symbolic link, /dxxsamples, is created during the samples set up, and points 

to IFS directory, /QIBM/UserData/DB2Extenders/XML/Samples. The term 

dxxsamples used throughout this book refers to either of these values. 
Creating an SQL collection (schema) for the samples 


You need to have a schema to run the samples because a set of stored 
procedures and tables with sample data will be created in this schema. 


When creating an SQL schema, it is recommended that the name of the 
schema the user ID that you will use while running the samples because of 
default schema rules in SQL. 


If you already have an SQL schema matching this user ID, you do not need to 
create a new schema. 


To create the schema: 

1. From the OS command line, open an SQL session by entering: 
STRSQL 

2. From the SQL session, enter: 
CREATE SCHEMA Userld 


Where UserId is user ID that you use when you run the samples. 


Setting up administration tools for iSeries 


The tools you can use for administration tools were described in 
“Administration environment” on page 41] You can choose any of these 


environments to perform the administration tasks. Some of these 
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environments require set up to be used with the XML Extender administration 
commands, the stored procedures, and the samples. The following sections 
describe the set up requirements. 


Setting up the Wizard 
See the XML Extender Web site: 


http://www. ibm.com/software/data/db2/extenders/xmlext/downloads.html 


Setting up the Qshell 
No set up required, except for installation of the Qshell option. 


Seiting up the iSeries Navigator interface 

You can use the iSeries Navigator to run administration commands, SQL 
statements, stored procedures, and to complete the Getting Started lessons. If 
you plan to use the iSeries Navigator, complete the following steps to 
download and build the sample programs. Building the sample programs 
prepares the environment for running the administration stored procedures 
and is required. 


1. Download and unpack the GetStart.exe file. 


a. Create a directory on the Windows operating system, called 
path/dxxsamples. path is the drive and directory under which the 
dxxsamples directory is to be located. 


b. From a Windows command line, enter: 
FIP SystemId 


Where Systemld is the host name of the iSeries system where you 
have restored the save file to the dxxsamples directory. 


Enter the requested user ID and password. 
c. Enter the following FTP command to change to binary mode: Binary. 


d. Enter the following FTP command to move the getting started exe file 
to the dxxsamples directory: 


get dxxsamples/getstart.exe path/dxxsamples/getstart.exe 
e. Close the FTP session with the following command: 
exit 
f. From the path/dxxsamples directory, enter: 
GetStart.exe 
2. Start the iSeries Navigator. 


3. Expand the tree for your iSeries system, and right click Database. A 
menu is displayed. 


4. From the menu, click Run SQL Scripts. 
5. Open the path/dxxsamples/setup.sql script file. 
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6. Change all occurrences of &SCHEMA to the schema name you created in 
“Creating an SQL collection (schema) for the samples” on page 48 
a. Click the Edit -> Replace from the menu. The Search and Replace 
window opens. 
b. From the Search and Replace window, replace all occurrences of 


&SCHEMA with your schema name. 


7. Change all occurrences of &DBNAME to the RDB database name for the 
system where you will run the sample programs. To determine this 
name, run the WRKRDBDIRE command from the OS command line. 
From the list of registered databases, select the name with the remote 
address of *LOCAL. 


a. Click the Edit -> Replace from the menu. The Search and Replace 
window opens. 


b. From the Search and Replace window, replace all occurrences of 
&DBNAME with the local database name. 


8. Save the setup.sq] file 
9. Repeat steps Js] for each SQL file. 
10. Open the path/dxxsamples/Setup.sq1 script file and click Run all. 


You are now ready to begin the Getting Started lessons, using the iSeries 
Navigator. 


The sample programs you have just built can be used to enter administration 
commands and DB2 commands. 


Preparing the sample programs for the iSeries command line 
You can use the OS command line to run administration commands and to 


complete the Getting Started lessons. 
To run administration commands, there is no set up. 


If you plan to use the OS command line for the samples and getting started 
lessons, run SETUP to build all sample programs. From the OS command line, 
enter: 


CALL DXXSAMPLES/SETUP 


Setting up the Getting Started environment for iSeries 


The following sections describe the required steps to set up the environment 
to perform the Getting Started lessons, which will help you use the provided 
samples for developing your own applications. 


You can use the following environments to complete the Getting Started 
lessons: 


* iSeries Navigator 
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* OS command line 


To use these environments, you must: 

1. Restore the sample source code to the samples library. Use the steps in 
“Unpack and restore sample files and getting started files” on page 47| 

2. Restore the XML sample files and the Getting Started executable to an IFS 
directory. Use the steps in |“Unpack and restore sample files and getting 
started files” on page 47 


3. Create an SOL Schema (collection). Use the steps in |“Creating an SQL 
ollection (schema) for the samples” on page 48 


4. Set up the environment from which you will complete the administration 
tasks. 


* When using the iSeries Navigator -|“Setting up the iSeries Navigator 
interface” on page 49 


* When using the OS command line -|“Preparing the sample programs for 
the iSeries command line” on page 50 


XML Extender administration planning 


When planning an application that uses XML documents, you first decide 
whether you will be: 


* Composing XML documents from data in the database. 


* Storing existing XML documents. If you will be storing XML documents, 
you must also decide if you want them to be stored as intact XML 
documents in a column or decomposed into regular DB2® data. 


After you make these decisions, you can then plan the rest for the following 
administration steps by deciding: 

* Whether to validate your XML documents 

* Whether to index XML column data for fast search and retrieval 

* How to map the structure of the XML document to DB2 relational tables 


How you use the XML Extender depends on what your application requires. 
You can compose XML documents from existing DB2 data and store XML 
documents in DB2, either as intact documents or as DB2 data. Each of these 
storage and access methods has different planning requirements. 


Choosing an access and storage method 
The XML Extender provides two access and storage methods to use DB2® as 
an XML repository: XML column and XML collection. You first need to decide 


which of these methods best match your application’s needs for accessing and 
manipulating XML data. 
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XML column 
Stores and retrieves entire XML documents as DB2 column data. The 
XML data is represented by an XML column. 


XML collection 
Decomposes XML documents into a collection of relational tables or 
composes XML documents from a collection of relational tables. 


The nature of your application determines which access and storage method 
is most suitable, as well as how to structure your XML data. 


You use the DAD file to associate XML data with DB2 tables through these 
two access and storage methods. shows how the DAD specifies the 
access and storage methods. 


XML document DAD 
<?xml?> : 
<!DOCTYPE...>—_| <Xcolumn> 
—_————> <table> 
<Order key="1"> <column> 
<column> 
<column> 
</table> 
</Order> </Xcolumn> 
XML document DAD 
<?xml?> \ Xx : llecti \ 
<!DOCTYPE...> a eich iene 
<«__—__|» <table> 4 _J1 Jy 
column> 
<Order key="1"> . 
ae 5 pl » 
<table> 
+_——> <column> <2 
</table> 
Oe </Xcollection> 


Figure 4. The DAD file maps the XML document structure to a DB2 relational data structure and 
specifies the access and storage method. 


The DAD file is an important part of administering the XML Extender. It 
defines the location of key files like the DTD, and specifies how the XML 
document structure relates to your DB2 data. Most important, it defines the 
access and storage method you use in your application. 
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Related concepts: 


When to use the XML column method” on page 53 
When to use the XML collection method” on page 53 


Related reference: 


Storage functions” on page 164 


When to use the XML column method 
Use XML columns in the following situations: 


The XML documents already exist or come from an external source and you 
prefer to store the documents in the native XML format. You want to store 
them in DB2® for integrity, archival, and auditing purposes. 


The XML documents are read frequently, but not updated. 


You want to use file name data types to store the XML documents external 
to DB2 in the local or remote file system and use DB2 for management and 
search operations. 


You need to perform range search based on the values of XML elements or 
attributes, and you know what elements or attributes will frequently be the 
search arguments. 


The documents have elements with large text blocks and you want to use 
the DB2 Text Extender for structural text search while keeping the entire 
documents intact. 


When to use the XML collection method 
Use XML collections in the following situations: 


You have data in your existing relational tables and you want to compose 
XML documents based on a certain DTD. 


You have XML documents that need to be stored with collections of data 
that map well to relational tables. 


You want to create different views of your relational data using different 
mapping schemes. 


You have XML documents that come from other data sources. You care 
about the data but not the tags, and want to store pure data in your 
database and you want the flexibility to decide whether to store the data in 
existing tables or in new tables. 


You need to store the data of entire incoming XML documents but often 
only want to retrieve a subset of them. 


You use the DAD file to associate XML data with DB2® tables through these 
two access and storage methods. The DAD file is an important part of 
administering the XML Extender. It defines the location of key files like the 
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DTD, and it specifies how the XML document structure relates to your DB2 
data. Most important, it defines the access and storage method you use in 
your application. 


Planning for XML columns 

Before you begin working with the XML Extender to store your documents, 

you need to understand the structure of the XML document so that you can 

determine how to index elements and attributes in the document. When 

planning how to index the document, you need to determine: 

* The XML user-defined type in which you will store the XML document 

* The XML elements and attributes that your application will frequently 
search, so that their content can be stored in side tables and indexed to 
improve performance 

* Whether or not to validate XML documents in the column with a DTD 

* The structure of the side tables and how they will be indexed 


Determining the XML data type for the XML column 
The XML Extender provides XML user defined types that you use to_define a 


column to hold XML documents. These data types are described in[Iable 8 
Table 8. The XML Extender UDTs 


User-defined type column Source data type Usage description 


XMLVARCHAR VARCHAR(varchar_len) Stores an entire XML 
document as VARCHAR 
data type within DB2. Used 
for small documents stored 
in DB2. 


XMLCLOB CLOB(clob_len) Stores an entire XML 
document as a CLOB data 
type within DB2. Used for 
large documents stored in 
DB2. 


XMLFILE VARCHAR(1024) Stores the file name of an 
XML document in DB2, and 
stores the XML document 
in a file local to the DB2 
server. Used for documents 
stored outside DB2. 


Determining elements and attributes to be indexed 
When you understand the XML document structure and the needs of your 


application, you can determine which elements and attributes to be searched. 
These are usually the elements and attributes that will be searched or 
extracted most frequently, or those that will be the most expensive to query. 
The location paths of each element and attribute can be mapped to relational 
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tables (side tables) that contain these objects in the DAD file for XML 
columns. The side tables are then indexed. 


For example, |Table 9] shows an example of types of data and location paths of 
element and attribute from the Getting Started scenario for XML columns. The 
data was specified as information to be frequently searched and the location 
paths point to elements and attributes that contain the data. These location 
paths can then be mapped to side tables in the DAD file. 


Table 9. Elements and attributes to be searched 


Data Location path 

order key / Order /@key 

customer / Order /Customer / Name 

price /Order/Part/ExtendedPrice 
shipping date /Order/Part/Shipment/ShipDate 
The DAD file 


For XML columns, the DAD file primarily specifies how documents that are 
stored in an XML column are to be indexed, and is an XML-formatted 
document, residing at the client. The DAD file specifies a DTD to use for 
validating documents inserted into the XML column. The DAD file has a data 
type of CLOB. This file can be up to 100 KB. 


The DAD file for XML columns contains an XML header, specifies the 
directory paths on the client for the DAD file and DTD, and provides a map 
of any XML data that is to be stored in side tables for indexing. 


To specify the XML column access and storage method, you use the following 
tag in the DAD file. 


<Xcolumn> 
Specifies that the XML data is to be stored and retrieved as entire 
XML documents in DB2 columns that are enabled for XML data. 


An XML-enabled column is of the XML Extender’s UDT. Applications 
can include the column in any user table. You access the XML column 
data mainly through SQL statements and the XML Extender’s UDFs. 


Planning for XML collections 


When planning for XML collections, you have different considerations for 
composing documents from DB2 data, decomposing XML document into DB2 
data, or both. The following sections address planning issues for XML 
collections, and address composition and decomposition considerations. 
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Validation 
After you choose an access and storage method, you can determine whether 


to validate your data. You validate XML data using a DTD. Using a DTD 
ensures that the XML document is valid and lets you perform structured 
searches on your XML data. The DTD is stored in the DTD repository. 


Recommendation: Validate XML data with a DTD. To validate, you need to 
have a DTD in the XML Extender repository. See |“Storing a DTD in the 
repository table” on page 70|to learn how to insert a DTD into the repository. 


The DTD requirements differ depending on whether you are composing or 
decomposing XML documents. The following list describes these 
requirements: 


* For composition, you can only validate generated XML documents against 
one DTD. The DTD to be used is specified in the DAD file. 


* For decomposition, you can validate documents for composition using 
different DTDs. In other words, you can decompose documents, using the 
same DAD file, but call DTDs that are different. To reference multiple 
DTDs, you must use the following guidelines: 


— At least one of the DTDs must be stored in the DTD_REF table. All of 
the DTDs can be stored in this table. 


— The DTDs should have a common structure, with differences in 
subelements. 


— You must specify validation in the DAD file. 


— The SYSTEM ID of the XML document must specify the DTD file using a 
full path name. 


— The DAD file contains the specification for how to decompose the 
document, and therefore, you can specify only common elements and 
attributes for decomposition. Elements and attributes that are unique to a 
DTD cannot be decomposed. 


Important: Make the decision whether to validate XML data before inserting 
XML data into DB2. The XML Extender does not support the validation of 
data that has already been inserted into DB2. 


Considerations: 
* You should use a DTD when using XML as interchange format. 
* Validating your XML data might have a small performance impact. 


* You can decompose only common elements and attributes when using 
multiple DTDs for decomposition. 


* You can decompose all elements and attributes when using one DTD. 
* You can use only one DTD for composition. 
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The DAD file 
For XML collections, the DAD file maps the structure of the XML document to 


the DB2 tables from which you either compose the document, or to where you 
decompose the document. 


For example, if you have an element called <Tax> in your XML document, 
you might need to map <Tax> to a column called TAX. You define the 
relationship between the XML data and the relational data in the DAD. 


The DAD file is specified either while enabling a collection, or when you use 
the DAD file in XML collection stored procedures. The DAD is an 
XML-formatted document, residing at the client. If you choose to validate 
XML documents with a DTD, the DAD file can be associated with that DTD. 
When used as the input parameter of the XML Extender stored procedures, 
the DAD file has a data type of CLOB. This file can be up to 100 KB. 


To specify the XML collection access and storage method, you use the 
following tag in the DAD file: 


<Xcollection> 
Specifies that the XML data is either to be decomposed from XML 
documents into a collection of relational tables, or to be composed 
into XML documents from a collection of relational tables. 


An XML collection is a virtual name for a set of relational tables that 
contains XML data. Applications can enable an XML collection of any 
user tables. These user tables can be existing tables of legacy business 
data or tables that the XML Extender recently created. You access 
XML collection data mainly through the stored procedures that the 
XML Extender provides. 


The DAD file defines the XML document tree structure, using the following 
kinds of nodes: 


root_node 
Specifies the root element of the document. 


element_node 
Identifies an element, while can be the root element or a child 
element. 


text_node 
Represents the CDATA text of an element. 


attribute_node 
Represents an attribute of an element. 
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shows a fragment of the mapping that is used in a DAD file. The 
nodes map the XML document content to table columns in a relational table. 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "dxx_install/dtd/dad.dtd"> 
<DAD> 


<Xcollection> 
<SQL_stmt> 


</SQL_stmt> 

<prolog>?xml version="1.0"?</prolog> 

<doctype>!DOCTYPE Order SYSTEM "dxx_install/sample/dtd/getstart.dtd 
"</doctype> <root_node> 


<element_node name="O0rder"> --> Identifies the element <Order> 
<attribute_node name="key"> --> Identifies the attribute "key" 
<column name="order_key"/> --> Defines the name of the column, 


"order_key", to which the element 
and attribute are mapped 
</attribute_node> 


<element_node name="Customer"> --> Identifies a child element of 
<Order> as <Customer> 
<text_node> --> Specifies the CDATA text for the 
element <Customer> 
<column name="customer"> --> Defines the name 


to which the child 

element is mapped 
</text_node> 
</element_node> 


</element_node> 


<root_node> 
</Xcollection> 
</DAD> 


Figure 5. Node definitions 


In this example, the first two columns in the SQL statement have elements 
and attributes mapped to them. 


You can use the XML Extender administration wizard or an editor to create 
and update the DAD file. 


Mapping schemes for XML collections 
If you are using an XML collection, you must select a mapping scheme that 


defines how XML data is represented in a relational database. Because XML 
collections must match a hierarchical structure that is used in XML documents 
with a relational structure, you should understand how the two structures 
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compare. shows how the hierarchical structure can be mapped to 
relational table columns. 


root_node 


element_node 
Order 


attribute_node element_node element_node 


Customer Part 


‘ 
| | 


element_node element_node 
Name Email 
text_node text_node 


customer_name 


‘| customer_email 


attribute node element_node element_node 
Color Quantity Tax 
color text_node text_node 
element_node quantity | | element_node tax | jelement_node 
Key ExtendedPrice Shipment 
text_node text_node 
part_key price 
element_node| |element_node 
ShipDate ShipMode 
text_node text_node 
Names of columns in DB2 tables date Goes 


Figure 6. XML document structured mapped to relational table columns 


The XML Extender uses the mapping scheme when composing or 
decomposing XML documents that are located in multiple relational tables. 
The XML Extender provides a wizard that assists you in creating the DAD 
file. However, before you create the DAD file, you must think about how your 
XML data is mapped to the XML collection. 


Types of mapping schemes: The mapping scheme is specified in the 
<Xcollection> element in the DAD file. The XML Extender provides two types 
of mapping schemes: SQL mapping and Relational Database (RDB_node) 
mapping. Both methods use the XPath model to define the hierarchy of the 
XML document. 
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SQL mapping 
Allows direct mapping from relational data to XML documents 
through a single SOL statement and the XPath data model. SQL 
mapping is used for composition; it is not used for decomposition. 
SQL mapping is defined with the SQL_stmt element in the DAD file. 
The content of the SQL_stmt is a valid SOL statement. The SOL_stmt 
maps the columns in the SELECT clause to XML elements or 
attributes that are used in the XML document. When defined for 
composing XML documents, the column names in the SQL statement’s 
SELECT clause are used to define the value of an attribute_node or a 
content of text_node. The FROM clause defines the tables containing 
the data; the WHERE clause specifies the join and search condition. 


The SQL mapping gives DB2 users the power to map the data using 
SQL. When using SQL mapping, you must be able to join all tables in 
one SELECT statement to form a query. If one SQL statement is not 
sufficient, consider using RDB_node mapping. To tie all tables 
together, the primary key and foreign key relationship is recommended 
among these tables. 


RDB_node mapping 
Defines the location of the content of an XML element or the value of 
an XML attribute so that the XML Extender can determine where to 
store or retrieve the XML data. 


This method uses the XML Extender-provided RDB_node, which 
contains one or more node definitions for tables, optional columns, 
and optional conditions. The tables and columns are used to define 
how the XML data is to be stored in the database. The condition 
specifies the criteria for selecting XML data or the way to join the 
XML collection tables. 


To define_a mapping scheme, you create a DAD with an <Xcollection> 
element. isu 7 an pare chow a fragment of a sample DAD file with an 
XML collection SQL mapping that composes a set of XML documents from 
data in three relational tables. 
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<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "dxx_install/dtd/dad.dtd"> 
<DAD> 
<dtdid>dxx_install/dad/getstart.dtd</dtdid> 
<validation>YES</validation> 
<Xcollection> 
<SQL_stmt> 
SELECT o.order_key, customer, p.part_key, quantity, price, tax, date, 
ship_id, mode, comment 
FROM order_tab o, part_tab p, 
(select db2xml].generate_unique() 
as ship_id, date, mode, from ship_tab) as 


WHERE p.price > 2500.00 and s.date > "1996-06-01" AND 
p.order_key = o.order_key and s.part_key = p.part_key 
</SQL_stmt> 
<prolog>?xml version="1.0"?</prolog> 
<doctype>!DOCTYPE DAD SYSTEM "dxx_install/dtd/ 
getstart.dtd"</doctype> 
<root_node> 
<element_node name="O0rder"> 
<attribute_node name="key"> 
<column_name="order_key"/> 
</attribute_node> 
<element_node name="Customer"> 
<text_node> 
<column name="customer"/> 
</text_node> 
<element_node> 


</element_node><!-end Part-> 
</element_node><!-end Order-> 
</root_node> 
</Xcollection> 
</DAD> 


Figure 7. SQL mapping scheme 


The XML Extender provides several stored procedures that manage data in an 


XML collection. These stored procedures support both types of mapping, but 
[Mapping 


require that the DAD file follow the rules that are described in 


Mapping scheme requirements: The following sections describe 
requirements for each type of the XML collection mapping schemes. 


Requirements for SQL mapping 


In this mapping scheme, you must specify the SQL_stmt element in 
the DAD <Xcollection> element. The SQL_stmt should contain a 
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single SQL statement that can join multiple relational tables with the 
query predicate. In addition, the following clauses are required: 


¢ SELECT clause 


— Ensure that the name of the column is unique. If two tables have 
the same column name, use the AS keyword to create an alias 
name for one of them. 


— Group the columns of the same table together, and use the 
logical hierarchical level of the relational tables. This means 
group the tables according to the level of importance as they 
map to the hierarchical structure of your XML document. In the 
SELECT clause, the columns of the higher-level tables should 
proceed the columns of lower-level tables. The following 
example demonstrates the hierarchical relationship among tables: 


SELECT o.order_key, customer, p.part_key, quantity, price, tax, 
ship_id, date, mode 


In this example, order_key and customer from table ORDER_TAB 
have the highest relational level because they are higher on the 
hierarchical tree of the XML document. The ship_id, date, and 
mode from table SHIP_TAB are at the lowest relational level. 


-— Use a single-column candidate key to begin each level. If such a 
key is not available in a table, the query should generate one for 
that table using a table expression and the user-defined function, 
generate_unique(). In the above example, the 0.order_key is the 
primary key for ORDER_TAB, and the part_key is the primary 
key of PART_TAB. They appear at the beginning of their own 
group of columns that are to be selected. Because the SHIP_TAB 
table does not have a primary key, one needs to be generated, in 
this case, ship_id. It is listed as the first column for the 
SHIP_TAB table group. Use the FROM clause to generate the 
primary key column, as shown in the following example. 


¢ FROM clause 


- Use a table expression and the user-defined function, 
generate_unique(), to generate a single key for tables that do not 
have a primary single key. For example: 

FROM order_tab as 0, part_tab as p, 


(select db2xml.generate_unique() as 
ship_id, date, mode from ship_tab) as s 


In this example, a single column candidate key is generated with 


the function, generate_unique() and given an alias named 
ship_id. 
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Use an alias name when needed to make a column distinct. For 
example, you could use 0 for ORDER_TAB, p for PART_TAB, 
and s for SHIP_TAB. 


* WHERE clause 


Specify a primary and foreign key relationship as the join 
condition that ties tables in the collection together. For example: 
WHERE p.price > 2500.00 AND s.date > "1996-06-01" AND 

p.order_key = o.order_key AND s.part_key = p.part_key 
Specify any other search condition in the predicate. Any valid 
predicate can be used. 


* ORDER BY clause 


Define the ORDER BY clause at the end of the SOL_stmt. 


Ensure that the column names match the column names in the 
SELECT clause. 


Specify the column names or identifiers that uniquely identify 
entities in the entity-relationship design of the database. An 
identifier can be generated using a table expression and the 
function generate_unique, or a user-defined function (UDF). 


Maintain the top-down order of the hierarchy of the entities. The 
column specified in the ORDER BY clause must be the first 
column listed for each entity. Keeping the order ensures that the 
XML documents to be generated do not contain incorrect 
duplicates. 


Do not qualify the columns in ORDER BY by any schema or 
table name. 


Although the SQL_stmt has the preceding requirements, it is powerful 
because you can specify any predicate in your WHERE clause, as long 
as the expression in the predicate uses the columns in the tables. 


Requirements when using RDB_node mapping 


When using this mapping method, do not use the element SQL_stmt 
in the <Xcollection> element of the DAD file. Instead, use the 
RDB_node element in each of the top nodes for element_node and for 
each attribute_node and text_node. 


There are no ordering restrictions on predicates of the root node 
condition. 


* RDB_node for the top element_node 


The top element_node in the DAD file represents the root element of 
the XML document. Specify an RDB_node for the top element_node 
as follows: 


Line ending characters are allowed in condition statements. 
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— Condition elements can reference a column name an unlimited 
number of times. 


— Specify all tables that are associated with the XML documents. 
For example, the following mapping specifies three tables in the 
RDB_node of the element_node <Order>, which is the top 
element_node: 
<element_node name="0rder"> 

<RDB_node> 
<table name="order_tab"/> 
<table name="part_tab"/> 
<table name="ship_tab"/> 
<condition> 
order_tab.order_key = part_tab.order_key AND 
part_tab.part_key = ship_tab.part_key 
</condition> 
</RDB_node> 


The condition element can be empty or missing if there is only 
one table in the collection. 


— If you are decomposing, or are enabling the XML collection 
specified by the DAD file, you must specify a primary key for 
each table. The primary key can consist of a single column or 
multiple columns, called a composite key. The primary key is 
specified by adding an attribute key to the table element of the 
RDB_node. When a composite key is supplied, the key attribute 
is specified by the names of key columns separated by a space. 
For example: 


<table name="part_tab" key="part_key price"/> 


The information specified for decomposition is ignored when 
composing a document. 


— Use the orderBy attribute to recompose XML documents 
containing elements or attributes with multiple occurrence back 
to their original structure. This attribute allows you to specify the 
name of a column that will be the key used to preserve the order 
of the document. The orderBy attribute is part of the table 
element in the DAD file, and it is an optional attribute. 


You must explicitly spell out the table name and the column name. 


* RDB_node for each attribute_node and text_node 


In this mapping scheme, the data resides in the attribute_node and 
text_node for each element_node. Therefore, the XML Extender 
needs to know from where in the database it needs to find the data. 
You need to specify an RDB_node for each attribute_node and 
text_node, telling the stored procedure from which table, which 
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column, and under which query condition to get the data. You must 
specify the table and column values; the condition value is optional. 


— Specify the name of the table containing the column data. The 
table name must be included in the RDB_node of the top 
element_node. In this example, for text_node of element <Price>, 
the table is specified as PART_TAB. 
<element_node name="Price"> 

<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="price"/> 
<condition> 
price > 2500.00 
</condition> 
</RDB_node> 
</text_node> 
</element_node> 

— Specify the name of the column that contains the data for the 
element text. In the previous example, the column is specified as 
PRICE. 


— Specify a condition if you want XML documents to be generated 
using the query condition. Allowable conditions are: 


- columname 
- operator 
- literal 


In the example above, the condition is specified as price > 
2500.00. Only the data meeting the condition is in the generated 
XML documents. The condition must be a valid WHERE clause. 


— If you are decomposing a document, or are enabling the XML 
collection specified by the DAD file, you must specify the 
column type for each attribute_node and text_node. This ensures 
the correct data type for each column when new tables are 
created during the enabling of an XML collection. Column types 
are specified by adding the attribute type to the column element. 
For example, 


<column name="order_key" type="integer"/> 


The information specified for decomposition is ignored when 
composing a document. 


* Maintain the top-down order of the hierarchy of the entities. This 
means ensure the element nodes are nested properly so that the 
XML Extender understands the relationship between the elements 
when composing or decomposing. For example, using the following 
DAD file, that does not nest Shipment inside of Part: 
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<element_node name="Part"> 
<element_node name="ExtendedPrice"> 
</element_node> 

</element_node> <!-- end of element Part --> 


<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 


</element_node> 
<element_node name="ShipMode"> 


</element_node> 
</element_node> <!-- end of element Shipment--> 


Which might produce an XML file in which the Part and Shipment 
are sibling elements. 


<Part color="black "> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850. 16</ExtendedPrice> 
<Tax>6 .000000e-2</Tax> 

</Part> 


<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 


<ShipMode>BOAT </ShipMode> 
</Shipment> 


When you would rather have a DAD that nests Shipment inside of 
Part: 


<element_node name="Part"> 
<element_node name="ExtendedPrice"> 
</element_node> 


<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 


</element_node> 
<element_node name="ShipMode"> 


</element_node> 


</element_node> <!-- end of element Shipment--> 
</element_node> <!-- end of element Part --> 
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Which produces an XML file with Shipment as a child element of 
Part: 
<Part color="black "> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850. 16</ExtendedPrice> 
<Tax>6.000000e-2</Tax> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>BOAT </ShipMode> 
</Shipment> 
</Part> 


With the RDB_node mapping approach, you don’t need to supply 
SQL statements. However, putting complex query conditions in the 
RDB_node element can be more difficult. 


Decomposition table size requirements 
Decomposition uses RDB_node mapping to specify how an XML document is 


decomposed into DB2 tables by extracting the element and attribute values 
into table rows. The values from each XML document are stored in one or 
more DB2 tables. Each table can have a maximum of 10240 rows decomposed 
from each document. 


For example, if an XML document is decomposed into five tables, each of the 
five tables can have up to 1024 rows for that particular document. If the table 
has rows for multiple documents, it can have up to 1024 rows for each 
document. If the table has 20 documents, it can have 20,480 rows, 1024 for 
each document. 


Using multiple-occurring elements (elements with location paths that can 
occur more than once in the XML structure) affects the number of rows 
inserted for each document. For example, a document that contains an 
element <Part> that occurs 20 times, might be decomposed as 20 rows in a 
table. When using multiple occurring elements, consider that a maximum of 
1024 rows can be decomposed into one table from a single document. 


Validating XML documents automatically 


After you choose an access and storage method, either XML Column or XML 
collection, you can determine whether to validate the XML documents. Unless 
you are storing XML documents for archival purposes, it is recommended that 
you first validate them before storing them into DB2. You can also validate 
XML documents that are composed from XML collections. 


You can have your XML data validated automatically by specifying YES for 


validation in the DAD file. To have a document validated when it is stored 
into DB2, you must specify a DTD within the <dtdid> element or in the 
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<!DOCTYPE> specification in the original document. To have a document 
validated when it is composed from an XML collection in DB2, you must 
specify a DTD within the <dtdid> element or within the <doctype> element in 
the DAD file. 


The following factors should be taken into consideration as you decide 

whether to validate your documents. 

* You do not need a DTD to store or archive XML documents. 

* It is important that you decide whether to validate before inserting XML 
data into DB2. The XML Extender does not support the validation of data 
after it has already been inserted into DB2. 

* Whether or not you choose to validate, it might be necessary to process the 
DTD in order to set entity values and attribute defaults. 

* If you specify NO for validation in the DAD, then the DTD specified by the 
XML document is not processed. 

* Validating your XML data has a performance impact. 


Enabling a database for XML 


To store or retrieve XML documents from DB2 with XML Extender, you 
enable the database for XML. The XML Extender enables the database you are 
connected to. 


When you enable a database for XML, the XML Extender does the following 

things: 

* Creates all the user-defined types (UDTs), user-defined functions (UDFs), 
and stored procedures 


* Creates and populates control tables with the necessary metadata that the 
XML Extender requires 


* Creates the DB2XML schema and assigns the necessary privileges 


The fully qualified name of an XML function is db2xml.function-name, 
where db2xml is an identifier that provides a logical grouping for SQL 
objects. You can use the fully qualified name anywhere you refer to a UDF 
or a UDT. You can also omit the schema name when you refer to a UDF or 
a UDT; in this case, DB2 uses the function path to determine the function or 


data type. 


For iSeries, you can enable a database for XML Extender using either your 
*SYSBAS database or an independent auxiliary storage pool (I[ASP). You can 
enable more than one IASP database for XML Extender. Only one IASP 
database can be active at a time. You cannot enable an IASP database for XML 
Extender if the *SYSBAS database is enabled. 


Procedure: 
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You can enable a database with the administration wizard or from a 
command line. 


The following example enables an existing database called SALES_DB. 
CALL QDBXM/QZXMADM PARM(enable_db SALES_DB) 


To enable a database using the administration wizard, you need to complete 
the following tasks: 
1. Start the administration wizard and click Enable database from the 
LaunchPad window. 
If a database is already enabled, the button will read Disable database. If 
the database is disabled, the button will read Enable database 
When the database is enabled, you are returned to the LaunchPad 
window. 


After you have enabled a database, you will be able to store and retrieve XML 
documents from DB2 using the XML extender. 


This task is part of the larger task of defining and enabling an XML column. 


An XML table is used to store intact XML documents. To store whole 
documents in your database using DB2 XML Extender, you must create a 
table so that it contains a column with an XML user-defined type (UDT). DB2 
XML Extender provides you with three user-defined types to store your XML 
documents as column data. These UDTs are: XMLVARCHAR, XMLCLOB, and 
XMLFILE. When a table contains a column of XML type, you can then enable 
it for XML. 


You can create as new table to add a column of XML type using the 
administration wizard or the command line. 


Procedure: 

To create a table with a column of XML type using the command line: 
Open the DB2 command prompt and type create table. 

For example, in a sales application, you might want to store an 


XML-formatted line-item order in a column called ORDER of a table called 
SALES _TAB. This table also has the columns INVOICE _NUM and 
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SALES_PERSON. Because it is a small order, you store the sales order using 
the XMLVARCHAR type. The primary key is INVOICE_NUM. The following 
CREATE TABLE statement creates a table with a column of XML type: 
CREATE TABLE sales_tab( 

invoice_num char(6) NOT PULL PRIMARY KEY, 


sales_person  varchar(20), 
order XMLVarchar) ; 


After you have created a table, the next step is to enable the column for XML 
data. 


Related concepts: 


* “Planning side tables” on page 75 
* |Chapter 11, “XML Extenders administration support tables” on page 251 


Storing a DTD in the repository table 


You can use a DTD to validate XML data in an XML column or in an XML 
collection. DTDs can be stored in the DTD repository table, a DB2 table called 
DTD_REF. The DTD_REF has a schema name of DB2XML. Each DTD in the 
DTD_REF table has a unique ID. The XML Extender creates the DTD_REF 
table when you enable a database for XML. You can insert the DTD from the 
command line or by using the administration wizard. 


Procedure: 


To insert the DTD using the administration wizard, you need to complete the 

following tasks: 

1. Start the administration wizard and click Import a DTD from the 
LaunchPad window to import an existing DTD file into the DTD 
repository for the current database. The Import a DTD window opens. 

2. Type the DTD file name in the DTD file name field or click ... to browse 
for an existing DTD file. 

3. Type the DTD ID in the DTD ID field. 

The DTD ID is an identifier for the DTD. It can also be the path specifying 
the location of the DTD on the local system. The DTD ID must match the 
value that is specified in the DAD file for the <DTDID> element. 

4. (Optional) Type the name of the author of the DTD in the Author field. 

5. Click Finish to insert the DTD into the DTD repository table, 
DB2XML.DTD_REF, and return to the LaunchPad window. 


To insert a DTD from the command line, issue a SOL INSERT statement from 


Table 10 on page 71} For example: 


INSERT into DB2XML.DTD_REF values('/dxxsamples/dtd/getstart.dtd'), 0, ‘userl', 
‘userl', ‘user1') 
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Table 10. The column definitions for the DTD Reference table 


Column name Data type Description 

DTDID VARCHAR(128) | ID of the DTD. 

CONTENT XMLCLOB Content of the DTD. 
USAGE_COUNT INTEGER Number of XML columns and XML 


collections in the database that use this 
DTD to define a DAD. 


AUTHOR VARCHAR(128) Author of the DTD, optional information 
for the user to input. 

CREATOR VARCHAR(128) User ID that does the first insertion. 

UPDATOR VARCHAR(128) User ID that does the last update. 


Enabling XML columns 


To store an XML document in a DB2 database, you must enable for XML the 
column that will contain the document. Enabling a column prepares it for 
indexing so that it can be searched quickly. You can enable a column by using 
the XML Extender administration wizard or the command line. The column 
must be of XML type. 


When the XML Extender enables an XML column, it performs the following 
operations: 


¢ Reads the DAD file to: 


— Check for the existence of the DTD in the DTD_REF table, if the DTDID 
was specified. 


— Create side tables on the XML column for indexing purpose. 
— Prepare the column to contain XML data. 


* Optionally creates a default view of the XML table and side tables. The 
default view displays the application table and the side tables. 


Column name limit: For iSeries, the column size limit in a view is 10 
characters. 


* Specifies a ROOT ID column, if one has not been specified. 


After you enable the XML column, you can: 

* Create indexes on the side tables 

* Insert XML documents in the XML column 

* Query, update, or search the XML documents in the XML column. 


You can enable XML columns using the administration wizard or from a DB2 
command line. 
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Procedure (using the Administration Wizard): 


To enable XML columns using the administration wizard: 

1. Set up and start the administration wizard. 

2. Click Work with XML Columns from the LaunchPad window to view 
the tasks related to the XML Extender columns. The Select a Task 
window opens. 

3. Click Enable a Column and then Next to enable an existing column. 

4. Select the table that contains the XML column from the Table name field. 

5. Select the column being enabled from the Column name field. The 
column must exist and be of XML type. 

6. Type the DAD path and file name in the DAD file name field, or click ... 
to browse for an existing DAD file. For example: 
dxx_install/dad/getstart.dad 

7. (Optional) Type the name of an existing table space in the Table space 
field. 


The table space default contains side tables that the XML Extender 
created. If you specify a table space, the side tables are created in the 
specified table space. If you do not specify a table space, the side tables 
are created in the default table space. 


8. (Optional) Type the name of the default view in the Default view field. 


When specified, the default view is automatically created when the 
column is enabled and joins the XML table and all of the related side 
tables. 


9. (Optional) Type the column name of the primary key for the table in the 
Root ID field. This is recommended. 


The XML Extender uses the value ofRoot ID as a unique identifier to 

associate all side tables with the application table. If the XML Extender 

adds the DXXROOT_ID column to the application table and generates an 

identifier. 

10. Click Finish to enable the XML column, create the side tables, and return 

to the LaunchPad window. 

* If the column is successfully enabled, you receive the message: column 
is enabled. 

* If the column is not successfully enabled, an error message is 
displayed, along with prompts for you to correct the values of the 
entry field until the column is successfully enabled. 


Procedure (using the Command Line): 


To enable an XML column using the command line use the DXXADM 
enable_column, which has the syntax and parameters explained in this section 
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Syntax: 


>>—dxxadm—enable_column—dbName—tbName—colName—DAD_fi Fiat > 
-v—default_view- 


> 


>< 


'_-r—roo t idl 


Parameters: 


dbName 
The name of the RDB database. 


tbName 
The name of the table that contains the column to be enabled. 


colName 
The name of the XML column that is being enabled. 


DAD_file 
The name of the file that contains the document access definition 
(DAD). 


default_view 
Optional. The name of the default view that the XML Extender 
created to join an application table and all of the related side tables. 


root_id Optional, but recommended. The column name of the primary key in 
the application table and a unique identifier that associates all side 
tables with the application table. Known as ROOT_ID. The XML 
Extender uses the value of ROOT_ID as a unique identifier to 
associate all side tables with the application table. If the ROOT ID is 
not specified, the XML Extender adds the DXXROOT_ID column to 
the application table and generates an identifier. 


Restriction: If the application table has a column name of 
DXXROOT_ID, you must specify the root_id parameter; otherwise, an 
error occurs. 


Example: 
From the Qshell: 


dxxadm enable_column SALES_DB myschema.sales_tab order getstart.dad 
-v sales_order_view -r INVOICE_NUMBER 


From the OS command line: 


CALL QDBXM/QZXMADM PARM(enable_column SALES_DB 'MYSCHEMA.SALES_TAB' 
ORDER 'getstart.dad' '-v' sales_order_view '-r' INVOICE_NUMBER) 
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From the iSeries Navigator: 


CALL MYSCHEMA.QZXMADM('enable_column', 'SALES_DB', 'MYSCHEMA.SALES TAB', 
'ORDER', 'getstart.dad', '-v sales_order_view', '-r INVOICE_NUMBER'); 


In this example, the ORDER column is enabled in the SALES_TAB table . The 
DAD file is getstart.dad, the default view is sales_order_view, and the ROOT 
ID is INVOICE NUMBER. 


Using this example, the SALES_TAB table has the following columns: 


Column name INVOICE_NUM_ |SALES_ PERSON| ORDER 
Data type CHAR(6) VARCHAR(20) | XMLVARCHAR 


The following side tables are created based on the DAD specification: 


ORDER_SIDE_TAB: 


Column name _ |ORDER KEY CUSTOMER INVOICE_NUM 

Data type INTEGER VARCHAR(50) CHAR(6) 

Path expression | /Order/@key /Order N/A 
/Customer/Name 


PART_SIDE_TAB: 


Column name PART_KEY PRICE INVOICE_NUM 

Data type INTEGER DOUBLE CHAR(6) 

Path expression | /Order/Part/@key | /Order/Part N/A 
/ExtendedPrice 


SHIP_SIDE_TAB: 


Column name DATE INVOICE_NUM 
Data type DATE CHAR(6) 
Path expression /Order/Part/Shipment/ShipDate |N/A 


All the side tables have the column INVOICE_NUM of the same type, 
because the ROOT ID is specified by the primary key INVOICE_NUM in the 
application table. After the column is enabled, the value of the 
INVOICE_NUM is inserted in side tables when a row is inserted in the main 


74 Administration and Programming for iSeries 


table. Specifying the default_view parameter when enabling the XML column, 
ORDER, creates a default view, sales_order_view. The view joins the above 
tables using the following statement: 
CREATE VIEW sales_order_view(invoice_num, sales_person, order, 
order_key, customer, part_key, price, date) 
AS 
SELECT sales_tab.invoice_num, sales_tab.sales_ person, sales_tab.order, 
order_tab.order_key, order_tab.customer, 
part_tab.part_key, part_tab.price, 
ship_tab.date 
FROM sales_tab, order_tab, part_tab, ship_tab 
WHERE sales_tab.invoice_num = order_tab.invoice_num 
AND sales_tab.invoice_num = part_tab.invoice_num 
AND sales_tab.invoice_num = ship_tab.invoice_num 


Planning side tables 


Side tables are DB2® tables used to extract the content of an XML document 
that will be searched frequently. The XML column is associated with side 
tables that hold the contents of the XML document. When the XML document 
is updated in the application table, the values in the side tables are 
automatically updated. 


[Figure 8|shows an XML column with side tables. 


XML document 


| <2xml?> 
<!IDOCTYPE...> | 


<Order key="1"> 


</Order> 


XML column 
with side tables 


Figure 8. An XML column whose content is mapped in side tables. There is an XML file in the 
column that is associated with side tables that hold the contents of the XML document. 


When planning for side tables, you must consider how to organize the tables, 
how many tables to create, and whether to create a default view for the side 
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tables. Base these decisions on whether elements and attributes can occur 
multiple times and your requirements for query performance. Do not plan to 
update the side tables in any way; they will be automatically updated when 
the document is updated in the XML column. 


Multiple occurrence: 


When elements and attributes occur multiple times in side tables, consider the 

following issues in your planning: 

* For elements or attributes in an XML document that have multiple 
occurrences, you must create a separate side table for each XML element or 
attribute with multiple occurrences, due to the complex structure of XML 
documents. This means that elements or attributes have location paths that 
occur multiple times and must be mapped to a table with only one column. 
You cannot have any other columns in the table. 


* When a document has multiple occurring location paths, XML Extender 
adds a column named DXX_SEQNO with a type of INTEGER in each side 
table to keep track of the order of elements that occur more than once. With 
DXX_SEQNO, you can retrieve a list of the elements using the same order 
as the original XML document by specifying ORDER BY DXX_SEQNO in 
an SQL query. 


Default views and query performance: 


When you enable an XML column, you can specify a default, read-only view 
that joins the application table with the side tables using a unique ID, called 
the ROOT ID. With the default view, you can search XML documents by 
querying the side tables. For example, if you have the application table 
SALES_TAB, and the side tables ORDER_TAB, PART_TAB and SHIP_TAB, 
your query might look as follows: 


SELECT sales_person FROM sales_order_view 
WHERE price > 2500.00 


The SQL statement returns the names of salespeople in the SALES_TAB who 
have orders stored in the column ORDER, and where the PRICE column is 
greater than 2500.00. 


The advantage of querying the default view is that it provides a virtual single 
view of the application table and side tables. However, the more side tables 
that are created, the more expensive the query. Therefore, creating the default 
view is only recommended when the total number of side-table columns is 
small. Applications can create their own views, joining the important side 
table columns. 
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Column name limit: For iSeries, the column size limit in a view is 10 
characters. To use a longer name, you must generate the view manually or 
use alias names 


Indexing side tables 
This task is part of the larger task of defining and enabling an XML column. 


Side tables contain the XML data in the columns that you specified when you 
created the DAD file. After you enable an XML column and create side tables, 
you can index the side tables. Indexing these tables helps you improve the 
performance of the queries against the XML documents. 


Procedure: 


To create an index for your side tables from a DB2 command line, type: 
DB2 CREATE INDEX 


from the DB2 command line. 


The following example creates indexes on four side tables using the DB2 
command prompt. 


CREATE INDEX KEY IDX 
ON ORDER SIDE_TAB(ORDER_KEY) 


CREATE INDEX CUSTOMER_IDX 
ON ORDER_SIDE_TAB(CUSTOMER) 


CREATE INDEX PRICE_IDX 
ON PART_SIDE_TAB(PRICE) 


CREATE INDEX DATE_IDX 
ON SHIP_SIDE_TAB(DATE) 


Composing XML documents by using SQL mapping 


You should use SQL mapping if you are composing an XML document and 
you want to use an SQL statement to define the table and columns from 
which you will derive the data in the XML document. This task is related to 
XML collections. SQL mapping can only be used for composing XML 
documents. A DAD file is used to compose the XML document with SQL 


mapping. 


Before you compose your documents, you must first map the relationship 
between your DB2 tables and the XML document. This step includes mapping 
the hierarchy of the XML document and specifying how the data in the 
document maps to a DB2 table 
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You can compose XML documents by using SQL mapping from the command 
line or by using the GUI administration wizard. 


Procedure: 


To compose XML documents from the command line you need to complete 
the following steps: 


1. 


Create a new document in a text editor and type the following syntax: 
<?XML version="1.0"?> 

Insert the <DAD></DAD> tags. 

This element will contain all the other elements. 


Specify the DTD ID that associates the DAD file with the XML document 
DTD. For example: 


<dtdid>path/dtd_name .dtd> 


The dtdid is useful only if you decide to validate the XML document. 


Insert the <validation></validation> tag to indicate whether DB2 XML 
Extender validates the XML document using the DTD in the repository 
table. 


a. If you want to validate the XML document, then type: 
<validation>YES</validation> 

b. If you do not wish to validate the XML document type: 
<validation>NO</validation> 


Enter <xXCollection> </Xcollection> tags to specify that you are using 
XML collections as the access and storage method for your XML data. 


Inside the <Xcollection> </Xcollection> tags, insert the <SQL_stmt> 
</SQL_stmt> tags to specify the SQL used for mapping the relational 
data to the XML documents. This statement is used to query data from 
DB2 tables. The following example illustrates how a single SQL query is 
specified. 
<SQL_stmt> 
SELECT o.order_key, customer_name, customer_email, p.part_key, color, 
quantity, price, tax, ship_id, date, mode from order_tab 0, part_tab p, 
(select db2xml.generate_unique() 
as ship_id, date, mode, part_key from ship_tab) as s 
WHERE o.order_key = 1 and 
p.price > 20000 and 
p.order_key = o.order_key and 
s.part_key = p.part_key 
ORDER BY order_key, part_key, ship_id 
</SQL_stmt> 


In the example above, the following guidelines were used to create the 
SQL statement for mapping the relational data to the XML document: 


78 Administration and Programming for iSeries 


a. Columns are specified in top-down order by the hierarchy of the XML 
document structure. 

b. The columns for an entity are grouped together 

c. The object ID column is the first column in each group. 

d. The Order_tab table does not have a single key column, and 
therefore, the generate_unique DB2 built-in function is used to 
generate the ship_id column. 

e. The object ID column is then listed in a top-down order in an ORDER 
BY statement. The column in ORDER By should not be qualified by 
any schema and the column names must match the column names in 
the SELECT clause. 

. Add the following prolog information to be used in the composed XML 

document: 

<prolog>?xml version="1.0"?</prolog> 

. Enter the <doctype> </doctype> tag. This tag contains the path to the 

DTD against which the composed document will be validated. For 

example: 

<doctype>! DOCTYPE Order SYSTEM "dxxsamples/dtd/getstart.dtd"</doctype> 

. Add the <root></root_node> tag to define the root element. All the 

elements and attributes that make up the XML document are specified 

within the root_node. 

. Map the elements and attributes in the XML document to element and 

attribute nodes that correspond to DB2 data using the following three 

types of nodes: 


element_node 
Specifies the element in the XML document. The element_node 
can have child element_nodes. 


attribute_node 
Specifies the attribute of an element in the XML document 


text_node 
Specifies the text content of the element and the column data in a 
relational table for bottom-level element_nodes. 


These nodes provide a path from the XML data to the DB2 data. 


a. For each element in the XML document, specify an <element_node> 
tag with the name attribute set to the element’s name as follows: 

b. For each attribute in the XML document specify an<attribute_node> 
tag with the name attribute set to the attribute’s name. The attributes 
are nested in their element node. For example: 
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c. For each bottom-level element specify <text_node> tags indicating 
that the element contains character data to be extracted from DB2 
when composing the document. 


d. For each bottom-level element_node, specify a <column> tag. These 
tags specify from which column to extract data when composing the 
XML document and are typically inside the <attribute_node> or the 
<text_node> tags. All column names defined must be in the 
<SQL_stmt> SELECT clause at the beginning of the DAD file. 


11. Ensure that you have an ending </root_node> tag after the last 
</element_node> tag. 


12. Ensure that you have an ending </Xcollection> tag after the 
</root_node> tag. 


13. Ensure that you have an ending </DAD> tag after the </Xcollection> 
tag. 
14. Save the file as file.dad. Where file is the name of you file. 


The following example shows a complete DAD: 


<?xml version'"1.0"> 
<!DOCTYPE DAD SYSTEM "C:\dxx_xml\test\dtd/dad.dtd'> 
<DAD> 
<validation>N0</validation> 
<Xcollection> 
<SQL_stmt> select o.order_key, customer_name, customer_email, 
p.part_key, color, qty, price, tax, ship_id, date, mode from order_tab o, 
part_tab p, (select db2xml.generate_unique() as 
ship_id, date, mode, part_key from ship_tab) s where 
o.order_key = 1 and p.price . 20000 and p.order_key 
= o.order_key and s.part_key =p.part_key ORDER BY order_key, 
part_key, ship_id</SQL_stmt> 
<prolog>?XML version="1.0"<?/prolog> 
<doctype>!DOCTYPE ORDER SYSTEM "dxxsamples\dtd/Order.dtd" 
</doctype> 
<root_node> 
<element_node name="O0rder"> 
<attribute_node name="key"> 
<column name="order_key"/> 
</attribute_node> 
<element_node name="Customer"> 
<element_node name="NAME"> 
<text_node><column name="customer_name"/></text_node> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="color"> 
<column name="color"/> 
</attribute_node> 
<element_node name="key"> 
<text_node><column name="part_key"/></text_node> 
</element_node> 
<element_node name ="Quantity"> 
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<text_node><column name="qty"/></text_node> 
</element_node> 
<element_node name="ExtendedPrice"> 
<text_node><column name="price"/></text_node> 
</element_node> 
<element_node name="Tax"> 
<text_node><column name="tax"/></text_node> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name=shipDate"> 
<text_node><column name="date"/><text_node> 
<element_node> 
<element_node name="ShipMode"> 
<text_node><column name="mode"/></text_node> 
</element_node> 
</element_node> 
</element_node> 
</element_node> 
</root_node> 
</Xcollection> 
</DAD> 


Composing XML collections by using RDB_node mapping 


RDB_node mapping uses the <RDB_node> tags to specify DB2 tables, 
columns, and conditions for an element or attribute node. Use this method if 
you want to compose XML documents by using an XML-like structure. The 
<RDB_node> uses the following elements: 


<table> 
defines the table corresponding to the element 


<column> 
defines the column containing the corresponding element 


<condition> 
optionally specifies a condition on the column 


The child elements that are used in the <RDB_node> element depend on the 
context of the node and use the following rules: 


If the node type is: The following RDB child elements are allowed: 
Table Column Condition’ 
Root element Y N Y 
Attribute Y ¥ optional 
Text ¥ Y optional 


Required with multiple tables 
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You can use the administration wizard or a command line to compose XML 
documents by using RDB_node mapping. 


Restrictions: 


If you compose your XML collections using RDB_node mapping, all 
statements of a given element must map to columns in the same table. 


Procedure: 


To compose an XML document from the command line using RDB_node 
mapping you need to complete the following steps. 


1. 


Open a text editor and create a DAD header by typing the following 
syntax: 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "path/dad.dtd"> 


Where "path/dad.dtd” is the path and file name of the DTD for the DAD. 


Insert the<DAD></DAD> tags. This element will contain all the other 
elements. 


Specify the DTD ID that associates the DAD file with the XML document 
DTD. For example: 


<dtdid>path/dtd_name .dtd</dtdid> 


The dtdid is useful only if you decide to validate the XML document. 


Insert the <validation></validation> tag to indicate whether DB2 XML 
Extender validates the XML document using the DTD in the repository 
table. 


a. If you want to validate the XML document, then type: 
<validation>YES</validation> 

b. If you do not wish to validate the XML document type: 
<validation>N0</validation> 


Enter <xXCollection> </Xcollection> tags to specify that you are using 
XML collections as the access and storage method for your XML data. 


Add the following prolog information: 

<prolog>?xml version="1.0"?</prolog> 

Add the <doctype></doctype> tags. For example: 

<doctype>! DOCTYPE Order SYSTEM "dxxsamples/dtd/getstart.dtd"</doctype> 


Insert the<root_node></root_node> tags. Inside the root_node tags, 
specify the elements and attributes that make up the XML document. 


After the <root_node> tag, map the elements and attributes in the XML 
document to element and attribute nodes that correspond to DB2 data. 
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Use the RDB_node element for the element_node, text_node, and 
attribute_node. These nodes provide a path from the XML data to the DB2 
data. To map the elements and attributes in your XML document, you 
must complete the following steps: 


* Specify an RDB_node for the top element_node. This element specifies 
all the tables that are associated with the XML document. 


* Specify an RDB_node for attribute_node. 
* Specify an RDB_node for the text_node 


a. To specify an RDB_node for the top element_node, enter <RDB_node 
>tags after the root_node tag in step 9. 


b. Define a table node for each table that contains data to be included in 
the XML document. For example, if you have three tables 
(ORDER_TAB, PART_TAB, and SHIP_TAB) that have column data to 
be in the document, create a table node for each. For example: 
<RDB_node> 
<table name="ORDER_TAB"> 
<table name="PART_TAB"> 
<table name="SHIP_TAB"> 
</RDB_node> 


If you are decomposing an XML document using the DAD file, you 
must specify a primary key for each table. The primary key can consist 
of a single column or multiple columns, called a composite key. The 
primary key is specified by adding an attribute key to the table 
element of the RDB_node. You must also specify a primary key for 
each table if you are going to enable a collection. The example below 
shows how you specify a key column for each table specified in the 
element_node. 

<RDB_node> 

<table name="ORDER_TAB" key="order_key"> 

<table name="PART_TAB" key="part_key"> 

<table name="SHIP_TAB" key="ship_key">> 

</RDB_node> 


Related concepts: 


* “Mapping schemes for XML collections” on page 125 
* |“Using location path with XML collections” on page 135 
* {Using the DAD file with XML collections” on page 196 


* |‘Requirements for RDB_Node mapping” on page 131 


Related tasks: 
Decomposing an XML collection by using RDB_node mapping” on page 
84] 
“Managing data in XML collections” on page 110 
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* |‘Updating, deleting, and retrieving XML collections” on page 121 


Related reference: 


* “XML Extenders composition stored procedures” on page 230 


Decomposing an XML collection by using RDB_node mapping 


Use RDB_node mapping to decompose XML documents. This method uses 
the <RDB_node> to specify DB2 tables, column, and conditions for an element 
or attribute node. The <RDB_node> uses the following elements: 


* <table>: defines the table corresponding to the element 
* <column>: defines the column containing the corresponding element 
* <condition>: optionally specifies a condition on the column 


The child elements that are used in the <RDB_node> depend on the context of 
the node and use the following rules: 


If the node type is: | RDB child element is used: 

Table Column Condition’ 
Root element x N x 
Attribute Y ¥ optional 
Text Y Y optional 


(1) Required with multiple tables 


Procedure using a command line:: 


To decompose XML documents using a command line, complete the following 
steps. 
1. Open any text editor. 
The DAD file must be either stored in an Integrated File System (IFS) 
directory, or created as a physical file member with a link in the IFS 
directory pointing to the member. 
2. Create the DAD header: 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "path/dad.dtd"> --> the path 
and file name of the DTD for the DAD 


3. Insert the <DAD></DAD> tags. 


4. After the <DAD> tag, specify the DTD ID that associates the DAD file 
with the XML document DTD. 


<dtdid>path/dtd_name.dtd> --> the path 
and file name of the DTD for your application 
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10. 


Specify whether to validate (that is, to use a DTD to ensure that the XML 
document is a valid XML document). For example: 


<validation>N0</validation> --> specify YES or NO 
Use the <Xcollection> element to define the access and storage method as 


XML collection. The access and storage methods define that the XML 
data is stored in a collection of DB2 tables. 


<Xcollection> 
</Xcollection> 


Add the following prolog information: 

<prolog>?xml version="1.0"?</prolog> 

Add the <doctype></doctype> tags. For example: 

<doctype>! DOCTYPE Order SYSTEM "dxxsample/dtd/getstart.dtd"</doctype> 


If you need to specify an encoding value for internationalization, add the 
ENCODING attribute and value. 
Define the root_node using the <root_node></root_node> tags. Inside 
the root_node, you specify the elements and attributes that make up the 
XML document. 
After the <root_node> tag, map the elements and attributes in the XML 
document to element and attribute nodes that correspond to DB2 data. 
These nodes provide a path from the XML data to the DB2 data. 
a. Define a top level, root element_node. This element_node contains: 

* Table nodes with a join condition to specify the collection. 

* Child elements 

* Attributes 


To specify the table nodes and condition: 

1) Create an RDB_node element: For example: 
<RDB_node> 
</RDB_node> 

2) Define a <table_node> for each table that contains data to be 
included in the XML document. For example, if you have three 
tables, ORDER_TAB, PART_TAB, and SHIP_TAB, that have 
column data to be in the document, create a table node for each. 
For example: 
<RDB_node> 
<table name="ORDER_TAB"> 
<table name="PART_TAB"> 
<table name="SHIP_TAB"> 
</RDB_node> 

3) Define a join condition for the tables in the collection. The syntax 
is: 
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table_name.table_column 
table_name.table_column 


table_name.table_column AND 
table_name.table_column ... 


For example: 


<RDB_node> 

<table name="ORDER_TAB"> 

<table name="PART_TAB"> 

<table name="SHIP_TAB"> 

<condition> 
order_tab.order_key = part_tab.order_key AND 
part_tab.part_key = ship_tab.part_key 

</condition> 

</RDB_node> 


4) Specify a primary key for each table. The primary key consists of 
a single column or multiple columns, called a composite key. To 
specify the primary key, add an attribute key to the table element 
of the RDB_node. The following example defines a primary key 
for each of the tables in the RDB_node of the root element_node 


Order: 
<element_node name="O0rder"> 
<RDB_node> 
<table name="order_tab" key="order_key"/> 
<table name="part_tab" key="part_key price"/> 
<table name="ship_tab" key="date mode"/> 
<condition> 
order_tab.order_key = part_tab.order_key AND 
part_tab.part_key = ship_tab.part_key 
</condition> 
<RDB_node> 


The information specified for decomposition is ignored when 
composing an XML document. 


The key attribute is required for decomposition, and when you 
enable a collection because the DAD file used must support both 
composition and decomposition. 


b. Define an <element_node> tag for each element in your XML 
document that maps to a column in a DB2 table. For example: 


<element_node name="name"> 
</element_node> 


An element node can have one of the following types of elements: 


* <text_node>: to specify that the element has content to a DB2 table; 
in this case it does not have child elements. 


* <attribute_node>: to specify an attribute; attribute nodes are 
defined in the next step 


¢ child elements 
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The text_node contains an RDB_node to map content to a DB2 table 
and column name. 


RDB_nodes are used for bottom-level elements that have content to 
map to a DB2 table. An RDB_node has the following child elements: 


* <table>: defines the table corresponding to the element 

* <column>: defines the column containing the corresponding 
element 

* <condition>: optionally specifies a condition on the column 


For example, you might have an XML element <Tax> for which you 
want to store the untagged content in a column called TAX: 


XML document: 
<Tax>@.02</Tax> 


In this case, you want the value 0.02 to be stored in the column TAX. 


In the DAD file, you specify an <RDB_node> to map the XML 
element to the DB2 table and column. 


DAD file: 


<element_node name="Tax"> 
<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="tax"/> 
</RDB_node> 
</text_node> 
</element_node> 


The <RDB_node> specifies that the value of the <Tax> element is a 
text value, the data is stored in the PART_TAB table in the TAX 
column. 


Define an <attribute_node> for each attribute in your XML document 
that maps to a column in a DB2 table. For example: 


<attribute_node name="key"> 
</attribute_node> 


The attribute_node has an RDB_node to map the attribute value to a 
DB2 table and column. An RDB_node has the following child 
elements: 


* <table>: defines the table corresponding to the element 


* <column>: defines the column containing the corresponding 
element 
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* <condition>: optionally specifies a condition on the column 


For example, you might have an attribute key for an element 
<Order>. The value of key needs to be stored in a column PART_KEY. 


XML document: 
<Order key="1"> 


In the DAD file, create an attribute_node for key and indicate the 
table where the value of 1 is to be stored. 


DAD file: 


<attribute_node name="key"> 
<RDB_node> 
<table name="part_tab"> 
<column name="part_key"/> 
<RDB_node> 
</attribute_node> 
11. Specify the column type for the RDB_node for each attribute_node and 
text_node. This ensures the correct data type for each column where the 
untagged data will be stored. To specify the column types, add the 
attribute type to the column element. The following example defines the 
column type as an INTEGER: 
<attribute_node name="key"> 
<RDB_node> 
<table name="order_tab"/> 
<column name="order_key" type="integer"/> 
</RDB_node> 
</attribute_node> 
12. Ensure that you have an ending </root_node> tag after the last 
</element_node> tag. 


13. Ensure that you have an ending </Xcollection> tag after the 
</root_node> tag. 


14. Ensure that you have an ending </DAD> tag after the </Xcollection> 
tag. 


Related tasks: 


* |“Decomposing XML documents into DB2 data” on page 116 
* |“Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* |“XML Extenders decomposition stored procedures” on page 245 
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Part 3. Programming 


This part describes programming techniques for managing your XML data. 


© Copyright IBM Corp. 1999, 2003 
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Chapter 3. XML columns 


This chapter describes how to manage data in XML columns using DB2. 


Managing data in XML columns 


When you use XML columns to store data, you store an entire XML document 
in its native format as column data in DB2. This access and storage method 
allows you to keep the XML document intact, while giving you the ability to 
index and search the document, retrieve data from the document, and update 
the document. 


After you enable a database for XML, the following user-defined types 
(UDTs), provided by XML Extender, are available for your use: 


XMLCLOB 
Use this UDT for XML document content that is stored as a character 
large object (CLOB) in DB2. 


XMLVARCHAR 
Use this UDT for XML document content that is stored as a 
VARCHAR in DB2. 


XMLFile 
Use this UDT for an XML document that is stored in a file on a local 
file system. 


You can create or alter application tables to have columns of XML UDT data 
type. These tables are known as XML tables. 


After you enable a column in a table for XML, you can create the XML 
column and perform the following management tasks: 


¢ Store XML documents in DB2 

¢ Retrieve XML data or documents from DB2 
* Update XML documents 

* Delete XML data or documents 


To perform all of these tasks, use the user-defined functions (UDFs) provided 
by XML Extender. Use default casting functions to store XML documents in 
DB2. Default casting functions cast the SQL base type to the XML Extender 
user-defined types and convert instances of a data type (origin) into instances 
of a different data type (target). 


© Copyright IBM Corp. 1999, 2003 91 


Related concepts: 


* |“XML Columns as a storage access method” on page 92 
* ‘Using indexes for XML column data” on page 94 


XML Columns as a storage access method 


Because XML contains all the necessary information to create a set of 
documents, there will be times when you want to store and maintain the 
document structure as it currently is. 


For example, if you are a news publishing company that has been serving 
articles over the Web, you might want to maintain an archive of published 
articles. In such a scenario, the XML Extender lets you store your complete or 
partial XML articles in a column of a DB2® table which is the XML column, as 
shown in 


XML document 


"| <?xml?> \ 


<!DOCTYPE...> 


<Order key="1"> 


</Order> 


XML CLOB 


Figure 9. Storing structured XML documents in a DB2 table column 


The XML column storage access method allows you to manage your XML 
documents using DB2. You can store XML documents in a column of XML 
type and you can query the contents of the document to find a specific 
element or attribute. You can associate and store a DTD in DB2 for one or 
more documents. Additionally, you can map element and attribute content to 
DB2 tables, called side tables. These side tables can be indexed for improved 
performance, but are not indexed automatically. The column that is used to 
store the document is called an XML column. It specifies that the column is 
used for the XML column access and storage method. 


In the document access definition (DAD) file you enter <Xcolumn> and 
</Xcolumn>tags to denote that the storage and access method you will use is 
XML column. The DAD will then map the XML element and attribute content 
that should to be stored in side tables. 
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Before you begin working with the XML Extender to store your documents, 

you need to understand the structure of the XML document so that you can 

determine how to index elements and attributes in the document. When 

planning how to index the document, you need to determine: 

* The XML user-defined type in which you will store the XML document 

* The XML elements and attributes that your application will frequently 
search, so that their content can be stored in side tables and indexed to 
improve performance 


* Whether or not you want to validate XML documents in the column with a 
DTD 


Defining and enabling an XML column 


You use XML columns to store and access entire XML documents in the 
database. This storage method allows you to store documents using the XML 
file types, index the columns in side tables, and query or search XML 
documents. 


Use XML columns when you want to store entire XML documents into a DB2 
table column if the document is not going to be frequently updated or if you 
want to store intact XML documents. 


If you want to map XML document structures to DB2 tables so that you can 
compose XML documents from existing DB2 data or decompose XML 
documents into DB2 data, then you should use XML collections instead of 
XML columns. 


Procedure: 


You can define and enable an XML column with a wizard or from a command 
line. 


To define and enable an XML column from the command line : 
1. Create a document access definition (DAD) file. 
2. Create a table in which the XML documents are stored. 


3. Enable the column for XML data. If the DAD specifies validation, then 
insert the column into dtd_ref table. 


4. Index side tables. 
The XML column is created as an XML user data type. After these tasks are 


complete, you will be able to store XML documents in the column. These 
documents can then be updated, searched, and extracted. 
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Related concepts: 


* “XML Columns as a storage access method” on page 92 


* |‘Using indexes for XML column data” on page 94 


* |“Lesson: Storing an XML document in an XML column” on page 10 


Related tasks: 


* |’Managing data in XML columns” on page 91 


Using indexes for XML column data 


An important planning decision when using XML columns, is whether to 
index the side tables for XML column documents. This decision should be 
made based on how often you need to access the data and how critical 
performance is during structural searches. 


When using XML columns, which contain entire XML documents, you can 
create side tables to contain columns of XML element or attribute values, then 
create indexes on these columns. You must determine the elements and 
attributes for which you need to create the index. 


XML column indexing allows frequently queried data of general data types 
(such as integer, decimal, or date) to be indexed using the native DB2® index 
support from the database engine. The XML Extender extracts the values of 
XML elements or attributes from XML documents and stores them in the side 
tables, allowing you to create indexes on these side tables. You can specify 
each column of a side table with a location path that identifies an XML 
element or attribute and an SQL data type. 


The XML Extender automatically populates the side table when you store 
XML documents in the XML column. 


For fast search, create indexes on these columns using the DB2 B-tree indexing 
technology. 


You must keep the following considerations in mind when creating an index: 

* For elements or attributes in an XML document that have multiple 
occurrences, you must create a separate side table for each XML element or 
attribute with multiple occurrences due to the complex structure of XML 
documents. 

* You can create multiple indexes on an XML column. 

* You can associate side tables with the application table using the ROOT ID, 
the column name of the primary key in the application table and a unique 
identifier that associates all side tables with the application table. You can 
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decide whether you want the primary key of the application table to be the 
ROOT ID, although it cannot be the composite key. This method is 
recommended. 


If the single primary key does not exist in the application table, or for some 
reason you don’t want to use it, the XML Extender alters the application 
table to add a column DXXROOT_ID, which stores a unique ID that is 
created at the insertion time. All side tables have a DXXROOT_ID column 
with the unique ID. If the primary key is used as the ROOT ID, all side 
tables have a column with the same name and type as the primary key 
column in the application table, and the values of the primary keys are 
stored. 


If you enable an XML column for the DB2 Text Extender, you can also use 
the Text Extender’s structural-text feature. The Text Extender has "section 
search" support, which extends the capability of a conventional full-text 
search by allowing search words to be matched within a specific document 
context that is specified by location paths. The structural-text index can be 
used with the XML Extender’s indexing on general SQL data types. 


Storing XML data 


Using the XML Extender, you can insert intact XML documents into an XML 
column. If you define side tables, the XML Extender automatically updates 
these tables. When you store an XML document directly, the XML Extender 
stores the base type as an XML type. 


Procedure: 


1. 
2. 
3. 


4. 


Ensure that you have created or updated the DAD file. 
Determine what data type to use when you store the document. 


Choose a method (casting functions or UDFs) for storing the data in the 
DB2" table. 


Specify an SQL INSERT statement that specifies the XML table and column 
to contain the XML document. 


The XML Extender provides two methods for storing XML documents: default 
casting functions and storage UDFs. 
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Table 11}shows when to use each method. 


Table 11. The XML Extender storage functions 


If the Store in DB2 as ... 
DB2 base 
type is ... XMLVARCHAR | XMLCLOB XMLDBCLOB XMLFILE 
VARCHAR] XMLVARCHAR() |N/A N/A XMLFile 
FromVarchar() 
CLOB N/A XMLCLOB() XMLDB XMLFile 
CLOB, FromCLOB() 
casting 
function 
DBCLOB |N/A N/A XMLDBCLOB, XMLFile 
casting function | FromDB 
CLOB, UDF 
FILE XMLVarcha XMLCLOB XMLDB XMLFILE 
rFromFile() FromFile() CLOBFrom 
File, UDF 


Default casting functions for storing XML data 


For each UDT, a default casting function exists to cast the SQL base type to 
the UDT. You can use the casting functions provided by XML Extender in 
your VALUES clause to insert data.|Table 12}shows the provided casting 
functions: 


Table 12. The XML Extender default casting functions 


Casting function Return type Description 

XMLVARCHAR(VARCHAR) XMLVARCHAR Input from memory buffer 
of VARCHAR 

XMLCLOB(CLOB) XMLCLOB Input from memory buffer 
of CLOB or a CLOB locator 

XMLFILE(VARCHAR) XMLFILE Store only the file name 

XMLDBCLOB(dbclob) XMLDBCLOB Input from memory buffer 
of DBCLOB 


For example, the following statement inserts a cast VARCHAR type into the 
XMLVARCHAR type: 


INSERT INTO sales_tab 
VALUES ('123456', ‘Sriram Srinivasan', DB2XML.XMLVarchar(:xml_buff)) 
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Storage UDFs for storing XML data 
For each XML Extender UDT, a storage UDF exists to import data into DB2 
from a resource other than its base type. For example, if you want to import 
an XML file document to DB2 as an XMLCLOB data type, you can use the 
function XMLCLOBFromFile(). 


‘Table 13}shows the storage functions provided by the XML Extender. 
Table 13. The XML Extender storage UDFs 


Storage user-defined 
function 


Return type 


Description 


XMLVarcharFromFile() 


XMLVARCHAR 


Reads an XML document 
from a file on the server 
and returns the value of the 
XMLVARCHAR data type. 


XMLCLOBFromFile() 


XMLCLOB 


Reads an XML document 
from a file on the server 
and returns the value of the 
XMLCLOB data type. 


XMLFileFromVarchar() 


XMLFILE 


Reads an XML document 
from memory as 
VARCHAR data, writes the 
document to an external 
file, and returns the value 
of the XMLFILE data type, 
which is the file name. 


XMLFileFromCLOB() 


XMLFILE 


Reads an XML document 
from memory as CLOB 
data or as a CLOB locator, 
writes the document to an 
external file, and returns 
the value of the XMLFILE 
data type, which is the file 
name. 


XMLFileFromDBCLOB() 


XMLFILE 


Reads an XML document 
from memory as DBCLOB 
or a DBCLOB locator, 
writes it to an external file, 
and returns the value of the 
XMLFILE data type, which 
is the file name. 


For example, using the XMLCLOBFromFile() function, the following statement 


stores a record in an XML table as an XMLCLOB: 
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EXEC SQL INSERT INTO sales_tab(ID, NAME, ORDER) 
VALUES('1234', 'MyName', 
XMLCLOBFromFile('dxxsample/xml/getstart.xml')) 


This example imports the XML document from the file named 
dxxsamples/xml/getstart.xml into the column ORDER in the table 
SALES_TAB. 


Retrieving XML data 


Using the XML Extender , you can retrieve either an entire document or the 
contents of elements and attributes. When you retrieve an XML column 
directly, the XML Extender returns the UDT as the column type. For details on 
retrieving data, see the following sections: 


The XML Extender provides two methods for retrieving data: default casting 
functions and the Content() overloaded UDF.|Table 14] shows when to use 
each method. 


Table 14. The XML Extender retrieval functions 


When the XML | Retrieve from DB2 as ... 

HYPE 8 VARCHAR CLOB DBCLOB FILE 

XMLVARCHAR | VARCHAR N/A N/A Content() 

XMLCLOB N/A XMLCLOB N/A Content() 

XMLDBCLOB_ |N/A N/A XMLDBCLOB, | Content(), UDF 
casting function 

XMLFILE N/A Content() N/A FILE 


Retrieving an entire XML document 
To retrieve an entire XML document: 


1. Ensure that you stored the XML document in an XML table and determine 
what data you want to retrieve. 

2. Choose a method (casting functions or UDFs) for retrieving the data in the 
DB2 table. 

3. If you are using the overloaded Content() UDF, determine the data type of 
the data that is being retrieved, and which data type is to be exported. 

4. Ensure that the XML column from which the element or attribute is to be 
extracted is defined as either an XMLVARCHAR, XMLCLOB as 
LOCATOR, or XMLFILE data type. 
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5. Specify an SQL query that specifies the XML table and column from which 
to retrieve the XML document. 


Default casting functions for retrieving XML data 
The default casting function provided by DB2 for UDTs converts an XML 


UDT to an SQL base type, and then operates on it. In your SELECT statement, 
you can use the casting functions that are provided by XML Extender to 
retrieve data.|Table 15|shows the provided casting functions. 


Table 15. The XML Extender default cast functions 


Casting used in SELECT Return type Description 

clause 

varchar(XMLVARCHAR) VARCHAR XML document in 
VARCHAR 

clob(XMLCLOB) CLOB XML document in CLOB 

dbclob(XMLDBCLOB) DBCLOB XML in double-byte CLOB 

varchar(XMLFile) VARCHAR XML file name in 
VARCHAR 

For example, the following statement retrieves the XMLVARCHAR and stores 


it in memory as a VARCHAR data type: 
EXEC SQL SELECT DB2XML.XMLVarchar(order) from SALES TAB 


Using the Content() overloaded UDF for retrieving XML data 
Use the Content() UDF to retrieve the document content from external storage 


to memory, or export the document from internal storage to an external file, 
which is a file that is external to DB2 on the DB2 server. 


For example, you might have your XML document stored as an XMLFILE 
data type. If you want to operate on it in memory, you can use the Content() 
UDE, which can take an XMLFILE data type as input and return a CLOB. 


The Content() UDF performs two different retrieval functions, depending on 
the specified data type. It can: 


* Retrieve a document from external storage and put it in memory. 


You can use Content() UDF to retrieve the XML document to a memory 
buffer or a CLOB locator (a host variable with a value that represents a 
single LOB value in the database server) when the document is stored as 
the external file. 

Use the following function syntax, where xmlobj is the XML column being 
queried: 

XMLFILE to CLOB: 

Content (xmlobj XMLFile) 
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* Retrieve a document from internal storage and export it to an external file. 


You can use the Content() UDF to retrieve an XML document that is stored 
inside DB2 as an XMLCLOB data type and export it to a file on the 
database server file system. The Content() UDF returns the name of the file 
as a VARCHAR data type. 


Use the following function syntax: 
XML type to external file: 
Content (xmlobj XML type, filename varchar(512)) 


Where: 


xmlobj Is the name of the XML column from which the XML content is to 
be retrieved. xmlobj can be of type XMLVARCHAR or XMLCLOB. 


filename 
Is the name of the external file in which the XML data is to be 
stored. 


In the example below, a small C program segment with embedded SQL 
statements (SQL statements coded within an application program) shows how 
an XML document is retrieved from a file to memory. This example assumes 
that the data type of the ORDER column is XMLFILE. 


EXEC SQL BEGIN DECLARE SECTION; 
SQL TYPE IS CLOB_LOCATOR xm1_buff; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL CONNECT TO SALES_DB 
EXEC SQL DECLARE c1 CURSOR FOR 
SELECT Content(order) from sales_tab 
EXEC SQL OPEN cl; 
do { 
EXEC SQL FETCH cl INTO :xml_buff; 
if (SQLCODE != 0) { 
break; 
} 
else { 
/* do whatever you need to do with the XML doc in buffer */ 
} 


} 
EXEC SQL CLOSE cl; 
EXEC SQL CONNECT RESET; 


Retrieving element contents and attribute values from XML documents 
You can retrieve (extract) the content of an element or the value of an 
attribute from one or more XML documents (single document or collection 
document search). The XML Extender provides user-defined extracting 
functions that you can specify in the SQL SELECT clause for each of the SQL 
data types. 
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Retrieving element content and attribute values is useful in developing your 
applications, because you can access XML data as relational data. For 
example, you might have 1000 XML documents that are stored in the ORDER 
column in the SALES_TAB table. To retrieve the names of all customers who 
have ordered items over $2500, use the following SQL statement with the 
extracting UDF in the SELECT clause: 


SELECT extractVarchar(Order, '/Order/Customer/Name') from sales_order_view 
WHERE price > 2500.00 


In this example, the extracting UDF retrieves the content of the <customer> 
element from the ORDER column and stores it as a VARCHAR data type. The 
location path is /Order/Customer/Name. Additionally, the number of returned 
values is reduced by using a WHERE clause, which specifies that only the 
contents of the <customer> element with a sub-element <ExtendedPrice> has 
a value greater than 2500.00. 


Table 16 on page 102}shows the UDFs that you can use to extract element 
content and attribute values, using the following syntax for or scalar 
functions: 


extractretrieved_datatype(xmlobj, path) 


Syntax: 


retrieved_datatype 
The data type that is returned from the extracting function; it can be 
one of the following types: 


* INTEGER 

* SMALLINT 

* DOUBLE 

* REAL 

* CHAR 

* VARCHAR 

* CLOB 

* DATE 

* TIME 

* TIMESTAMP 
xmlobj The name of the XML column from which the element or attribute is 


to be extracted. This column must be defined as one of the following 
XML user-defined types: 


° XMLVARCHAR 
* XMLCLOB as LOCATOR 
° XMLFILE 
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path The location path of the element or attribute in the XML document 
(such as /Order/Customer/Name). 


Restriction: Extracting UDFs can support location paths that have predicates 
with attributes, but not elements. For example, the following predicate is 
supported: 

'/Order/Part[@color="black "]/ExtendedPrice' 


The following predicate is not supported: 
'/Order/Part/Shipment/[Shipdate < "11/25/00"]' 


Table 16}shows the extracting functions, both in scalar and table format. 
Table 16. The XML Extender extracting functions 


Scalar function Returned column name Return type 
(table function) 
extractInteger() returnedInteger INTEGER 
extractSmallint() returnedSmallint SMALLINT 
extractDouble() returnedDouble DOUBLE 
extractReal() returnedReal REAL 
extractChar() returnedChar CHAR 
extractVarchar() returned Varchar VARCHAR 
extractCLOB() returnedCLOB CLOB 
extractDate() returnedDate DATE 
extractTime() returnedTime TIME 
extractTimestamp() returnedTimestamp TIMESTAMP 


Scalar function example: In the following example, one value is inserted with 
the attribute key value of 1. The value is extracted as an integer and 
automatically converted to a DECIMAL type. 


CREATE TABLE t1(key decimal (3,2)); 
INSERT into tl 
(SELECT db2xml.extract Integer (db2xml .xmlfile('c:\dxx\samples\xml\getstart.xml'), 
'/Order [@key="1"]/@key') 
FROM db2xml.onerow) ; 
SELECT * from tl; 


Table function example: In the following example, each key value (@key) for 
the sales order is extracted as an INTEGER. 


SELECT * from table(DB2XML.extractIntegers (DB2XML.XMLFile 
('/dxxsamples/xml/getstart.xml'), '/Order/@key')) as x; 
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Updating XML data 


With the XML Extender , you can update the entire XML document by 
replacing the XML column data, or you can update the values of specified 
elements or attributes. 


Procedure 


To update XML data: 


1. Store the XML document in an XML table and determine what data you 
want to retrieve. 


2. Choose a method for updating the data in the DB2 table (casting functions 
or UDFs). 


3. Specify an SQL query that specifies the XML table and column to update. 


Important: When updating a column that is enabled for XML, the XML 
Extender automatically updates the side tables to reflect the changes. Do not 
update side tables directly. Doing so can cause data inconsistency problems. 


Updating an entire XML document 


You can update an XML document by using a default casting function, or by 
using a storage UDF. 


Updating with a default casting function 
For each user-defined type (UDT), a default casting function exists to cast the 


SQL base type to the UDT. You can use the XML Extender-provided casting 
functions to update the XML document. 


For example, the following statement updates the XMLVARCHAR type from 
the cast VARCHAR type, assuming that xml_buf is a host variable that is 
defined as a VARCHAR type. 


UPDATE sales_tab SET=DB2XML.XMLVarchar(:xml_buff) 


Updating XML documents with a storage UDF 
For each of the XML Extender UDTs, a storage UDF exists to import data into 


DB2 from a resource other than its base type. You can use a storage UDF to 
update the entire XML document by replacing it. 


The following example updates the XML object from the file named 
dxxsample/xml/getstart.xml to the ORDER column in the SALES_TAB table. 


UPDATE sales_tab 
set order = XMLVarcharFromFile('dxxsample 
/xml/getstart.xml) WHERE sales_person = 'MyName' 
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Updating specific elements and attributes of an XML document 
Use the Update UDF to make specific changes, rather than updating the entire 
document. When you use this UDF, you specify the location path of the 
element or attribute whose value will be replaced. You do not need to edit the 
XML document; the XML Extender makes the change for you. 


Syntax: 
Update(xmlobj, path, value) 


The syntax has the following components: 


xmlobj The name of the XML column for which the value of the element or 
attribute is to be updated. 


path The location path of the element or attribute that is to be updated. 


value The new value that is to be updated. 


For example, the following statement replaces the value of the <Customer> 
element with ‘IBM’: 
UPDATE sales_tab 


set order = Update(order, '/Order/Customer/Name', 'IBM') 
WHERE sales_person = ‘Sriram Srinivasan' 


Multiple occurrence: When you specify a location path in the Update UDF, 
the content of every element or attribute with a matching path is updated 
with the supplied value. If a location path occurs in a document more than 
once, the Update UDF replaces all of the existing values with the value 
provided in the value parameter. 


Searching XML documents 


Searching XML data is similar to retrieving XML data: both techniques 
retrieve data for further manipulation but they search by using the content of 
the WHERE clause as the criteria for retrieval. 


The XML Extender provides several methods for searching XML documents 
that are stored in an XML column. You can: 


¢ Search document structure and return results based on element content or 
attribute values. 


* Search a view of the XML column and its side tables. 
* Search the side tables directly for better performance. 
* Search using extracting UDFs with WHERE clauses. 


* Use the DB2® Text Extender to search column data within the structural 
content for a text string. 
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With XML Extender you can use indexes to quickly search columns in side 
tables. These columns contain XML element content or attribute values that 
are extracted from XML documents. By specifying the data type of an element 
or attribute, you can search on an SQL data type or do range searches. For 
example, in the purchase order example, you could search for all orders that 
have an extended price of over 2500.00. 


Additionally, you can use the Text Extender to do structural text search or full 
text search. For example, you might have a column called RESUME that 
contains resumes in XML format. If you want to find the names of all 
applicants who have Java’™ skills, you could use the DB2 Text Extender to 
search on the XML documents for all resumes where the <skill> element 
contains the character string “JAVA”. 


The following section describes search methods: 


* {Searching the XML document by structure” 


Searching the XML document by structure 


Using the XML Extender search features, you can search XML data in a 
column based on the document structure (the elements and attributes in the 
document). To search the data, you can: 


* Directly query the side tables. 
* Use a joined view. 
* Use extracting UDFs. 


These search methods are described in the following sections and use 
examples based on the following scenario. The SALES_TAB table has an XML 
column named ORDER. This column has three side tables, 
ORDER_SIDE_TAB, PART_SIDE_TAB, and SHIP_SIDE_TAB. A default view, 
sales_order_view, was specified when the ORDER column was enabled. This 
view joins these tables using the following CREATE VIEW statement: 
CREATE VIEW sales_order_view(invoice_num, sales_person, order, 
order_key, customer, part_key, price, date) 
AS 
SELECT sales_tab.invoice_num, sales_tab.sales_person, sales_tab.order, 
order_side_tab.order_key, order_side_tab.customer, 
part_side_tab.part_key, ship_side_tab.date 
FROM sales_tab, order_side_tab, part_side_tab, ship_side_tab 
WHERE sales_tab.invoice_num = order_side_tab.invoice_num 
AND sales_tab.invoice_num = part_side_tab.invoice_num 
AND sales_tab.invoice_num = ship_side_tab.invoice_num 


Searching with direct query on side tables 
Direct query with subquery search provides the best performance for a 


structural search when the side tables are indexed. You can use a query or 
subquery to search side tables correctly. 
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For example, the following statement uses a query and subquery to directly 
search a side table: 
SELECT sales_person from sales_tab 

WHERE invoice_num in 


(SELECT invoice_num from part_side_tab 
WHERE price > 2500.00) 


In this example, invoice_num is the primary key in the SALES_TAB table. 


Searching from a joined view 
The XML Extender can create a default view that joins the application table 


and the side tables using a unique ID. You can use this default view, or any 
view that joins an application table and side tables, to search column data and 
query the side tables. This method provides a single virtual view of the 
application table and its side tables. However, the more side tables that are 
created, the longer the query takes to run. 


Tip: You can use the root ID, or DXXROOT_ID (created by the XML 
Extender), to join the tables when creating your own view. 


For example, the following statement searches the view named 
SALES_ORDER_VIEW and returns the values from the SALES_PERSON 
column where the line item orders have a price greater than 2500.00. 


SELECT sales_person from sales_order_view 
WHERE price > 2500.00 


Searching with extracting UDFs 
You can also use XML Extender’s extracting UDFs to search on elements and 


attributes, when you did not create indexes or side tables for the application 
table. Using the extracting UDFs to scan the XML data is very expensive and 
should only be used with WHERE clauses that restrict the number of XML 
documents that are included in the search. 


Example: The following statement searches with an extracting XML Extender 
UDF: 
SELECT sales_person from sales_tab 
WHERE extractVarchar(order, '/Order/Customer/Name' ) 
like '%IBM%' 
AND invoice_num > 100 


In this example, the extracting UDF extracts </Order/Customer/Name> 
elements that contain the substring IBM. 


Searching on elements or attributes with multiple occurrence 
When searching on elements or attributes that have multiple occurrence, use 


the DISTINCT clause to prevent duplicate values. 
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Example: The following statement searches with the DISTINCT clause: 


SELECT sales_person from sales_tab 
WHERE invoice_num in 
(SELECT DISTINCT invoice_num from part_side_tab 
WHERE price > 2500.00 ) 


In this example, the DAD file specifies that /Order/Part/Price has multiple 
occurrence and creates a side table, PART_SIDE_TAB, for it. The 
PART_SIDE_TAB table might have more than one row with the same 
invoice_num. Using DISTINCT returns only unique values. 


Related samples: 
* “dxx_xml -- s-getstart_queryCol_NT-cmd.htm” 
* “dxx_xml -- s-getstart_queryCol-cmd.htm” 


Deleting XML documents 


Use the SQL DELETE statement to delete the row containing an XML 
document from an XML column. You can specify a WHERE clause to delete 
specific documents. 


For example, the following statement deletes all documents that have a value 
for <ExtendedPrice> greater than 2500.00: 


DELETE from sales_tab 
WHERE invoice_num in 
(SELECT invoice_num from part_side_tab 
WHERE price > 2500.00) 


The corresponding rows in the side tables are automatically deleted. 


Related concepts: 


* (“XML Columns as a storage access method” on page 92 


Related tasks: 


* (“Managing data in XML columns” on page 91 


Limitations when invoking functions from Java Database (JDBC) 


When using parameter markers in functions, a JDBC restriction requires that 
the parameter marker for the function must be cast to the data type of the 
column into which the returned data will be inserted. The function selection 
logic does not know what data type the argument might turn out to be, and it 
cannot resolve the reference. 
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For example, JDBC cannot resolve the following code: 
DB2XML.XMLdefault_casting_function(length) 


You can use the CAST specification to provide a type for the parameter 
marker, such as VARCHAR, and then the function selection logic can proceed: 


DB2XML.XMLdefault_casting_function(CAST(? AS cast_type(length) ) 


Example 1: In the following example, the parameter marker is cast as 
VARCHAR. The parameter being passed is an XML document, which is cast 
as VARCHAR(1000) and inserted into the column ORDER. 


String query = "insert into sales_tab(invoice_num, sales person, order) values 
(?,?,DB2XML.XMLVarchar(cast (? as varchar(1000))))"; 


Example 2: In the following example, the parameter marker is cast as 
VARCHAR. The parameter being passed is a file name and its contents are 
converted to VARCHAR and inserted into the column ORDER. 


String query = "insert into sales_tab(invoice_num, sales_person, order) values 
(?,?,DB2XML.XMLVarcharfromFILE(cast (? as varchar(1000))))"; 
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Chapter 4. Managing data in XML collections 


XML Collections as a storage and access method 


Relational data is either decomposed from incoming XML documents or used to 
compose outgoing XML documents. Decomposed data is the untagged content 
of an XML document stored in one or more database tables. Or, XML 
documents are composed from existing data in one or more database tables. If 
your data is to be shared with other applications, you might want to be able 
to compose and decompose incoming and outgoing XML documents and 
manage the data as necessary to take advantage of the relational capabilities 
of DB2. This type of XML document storage is called XML collection. 


An example of an XML collection is shown in|Figure 10 


XML document 


<?xml?> 
<!DOCTYPE...> 


<Order key="1"> 


</Order> 


Collection 


Figure 10. Storing documents as untagged data in DB2 tables 


The XML collection is defined in a DAD file, which specifies how elements 
and attributes are mapped to one or more relational tables. The collection is a 
set of columns, associated with a DAD file, that contain the data in a 
particular XML document or set of XML documents. You can define a 
collection name by enabling it, and then refer to it by name when issuing a 
stored procedure to compose or decompose XML documents, called an 
enabled XML collection. The collection is given a name so that it is easily run 
with stored procedures when composing and decomposing the XML 
documents. 


When you define a collection in the DAD file, you use one of two types of 
mapping schemes, SQL mapping or RDB_node mapping. that define the tables, 
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columns, and conditions used to associate XML data with DB2 tables. SQL 
mapping uses SQL SELECT statements to define the DB2 tables and 
conditions used for the collection. RDB_node mapping uses an XPath-based 
relational database node, or RDB_node, which has child elements. 


Stored procedures are provided to compose or decompose XML documents. 
Stored procedure names are qualified by DB2XML, which is the schema name 
of the XML Extender. 


Managing data in XML collections 


An XML collection is a set of relational tables that contain data that is mapped 
to XML documents. This access and storage method lets you compose an 
XML document from existing data, decompose an XML document, and use 
XML as an interchange method. 


The relational tables that make up the collection can be new tables, or existing 
tables that have data that is to be used with the XML Extender to compose 
XML documents for your applications. Column data in these tables does not 
contain XML tags; it contains the content and values that are associated with 
elements and attributes, respectively. Stored procedures act as the access and 
storage method for storing, retrieving, updating, searching, and deleting XML 
collection data. 


You can increase the CLOB sizes for the results of the stored procedures. 


Composing XML documents from DB2 data 


Composition is the generation of a set of XML documents from relational data 
in an XML collection. You can compose XML documents using stored 
procedures. To use these stored procedures, create a document access 
definition (DAD) file. A DAD file specifies the mapping between the XML 
document and the DB2 table structure. The stored procedures use the DAD 
file to compose the XML document. 


Prerequisites: 


Before you begin composing XML documents, perform the following steps: 


1. Map the structure of the XML document to the relational tables that 
contain the contents of the element and attribute values. 


2. Select a mapping method: SQL mapping or RDB_node mapping. 
3. Prepare the DAD file. 
4. Optional: Enable the XML collection. 
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The XML Extender provides four stored procedures, dxxGenXML(), 
dxxGenXMLCLOB(), dxxRetrieveXML(), and dxxRetrieveXMLCLOB to 
compose XML documents. The frequency with which you plan to update the 
XML document is a key factor in selecting the stored procedure that you will 
use. 


Documents that will be updated occasionally 
If your document will be updated only occasionally, use the dxxGenXML 


stored procedure to compose the document. You do not have to enable a 
collection to use this stored procedure. It uses a DAD file instead. 


The dxxGenXML stored procedure constructs XML documents using data that 
is stored in XML collection tables, which are specified by the <Xcollection> 
element in the DAD file. This stored procedure inserts each XML document as 
a row into a result table. You can also open a cursor on the result table and 
fetch the result set. The result table should be created by the application and 
always has one column of VARCHAR, CLOB, XMLVARCHAR, or XMLCLOB 


type. 


Additionally, if the value of the validation element in the DAD file is YES, the 
XML Extender adds the column DXX_VALID of INTEGER type into the result 
table if the DXX_VALID column is not in the table yet. The XML Extender 

inserts a value of 1 for a valid XML document and 0 for an invalid document. 


The stored procedure dxxGenXML also allows you to specify the maximum 
number of rows that are to be generated in the result table. This shortens 
processing time. The stored procedure returns the actual number of rows in 
the table, along with any return codes and messages. 


The corresponding stored procedure for decomposition is dxxShredXML,; it 
also takes the DAD as the input parameter and does not require that the XML 
collection be enabled. 


To compose an XML collection using the dxxGenXML stored procedure, 
embed a stored procedure call in your application using the following stored 
procedure declaration: 


dxxGenXML (CLOB (100K) DAD, /* input */ 
char(32 ) resultTabName, /* input */ 
char (30) result_column, /* input */ 
char (30) valid_column, /* input */ 
integer overrideType, /* input */ 
varchar(1024) override, /* input */ 
integer maxRows , /* input */ 
integer numRows , /* output */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 
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Example: The following example composes an XML document: 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 


DAD */ 


of the result table */ 
of the result column «/ 
of the valid column, will set to NULL */ 


override, will set to NULL*/ 
defined in dxx.h */ 
maximum number of rows */ 


actual number of rows */ 
return error code */ 
error message text */ 


EXEC SQL BEGIN DECLARE SECTION; 
SQL TYPE is CLOB(100K) dad;  /* 
char result_tab[32]; /* name 
char result_colname[32]; /* name 
char valid_colname[32]; /* name 
char override[2]; /* 
short overrideType; /* 
short max_row; /* 
short num_row; /* 

long returnCode; /* 

char returnMsg[1024] ; /* 
short dad_ind; 

short rtab_ind; 

short rcol_ind; 

short vcol_ind; 

short ovtype_ind; 

short ov_ind; 

short maxrow_ind; 

short numrow_ind; 

short returnCode_ind; 

short returnMsg_ind; 


EXEC SQL END DECLARE SECTION; 


FILE 
long 


*file_handle; 
file_length=0; 


/* create table */ 
EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initialize the DAD CLOB object. */ 


file_handle = fopen("/dxx/dad 


/getstart_xcollection.dad", "r"); 

if ( file_handle != NULL ) { 
file_length = fread ((void *) &dad.data, 

1, FILE_SIZE, file_handle); 

if (file_length == 0) { 

printf ("Error reading dad file 


\n", ); 


/dxx/dad 
/getstart_xcollection.dad\n") ; 
re = -1; 
goto exit; 
} else 
dad.length = file_length; 
} 
else { 
printf("Error opening dad file 
re = -l; 
goto exit; 
} 
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/* initialize host variable and indicators */ 
strcpy(result_tab,"xml_order_tab"); 
strcpy(result_colname, "xmlorder") 
valid_colname = '\0'; 

override[0] = '\0'; 

overrideType = NO_OVERRIDE; 

max_row = 500; 

num_row = Q; 
returnCode 
msg_txt [0] 
dad_ind = 0; 
rtab_ind = 0; 
rcol_ind s 
vcol_ind = -1; 
ov_ind = -1; 
ovtype_ind : 
maxrow_ind 3 
numrow_ind 1; 
returnCode_ind = -1; 
returnMsg_ind = -1; 


0; 
'\O's 


i) 
i) 
d 


/* Call the store procedure */ 
EXEC SQL CALL "DB2XML!dxxGenXML" 
(:dad:dad_ind; 
sresult_tab:rtab_ind, 
:result_colname:rcol_ind, 
:valid_colname:vcol_ind, 
:overrideType:ovtype_ind, :override:ov_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode:returnCode_ind,:returnMsg:returnMsg ind); 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


exit: 
return rc; 


After the stored procedure is called, the result table contains 250 rows because 
the SQL query specified in the DAD file generated 250 XML documents. 


Documents that will be updated frequently 
If your document will be updated frequently, use the dxxRetrieveXML stored 


procedure to compose the document. Because the same tasks are repeated, 
improved performance is important. 


The dxxRetrieveXML stored procedure works in the same way as the 


dxxGenXML stored procedure, except that it takes the name of an enabled 
XML collection instead of a DAD file. When an XML collection is enabled, a 
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DAD file is stored in the XML_USAGE table. Therefore, the XML Extender 
retrieves the DAD file and uses it to compose the document in the same way 
as the dxxGenXML stored procedure. 


The dxxRetrieveXML stored procedure allows the same DAD file to be used 
for both composition and decomposition. 


The corresponding stored procedure for decomposition is dxxInsertXML,; it 
also takes the name of an enabled XML collection. 


To compose an XML collection using the dxxRetrieveXML stored procedure, 
embed a stored procedure call in your application using the following stored 
procedure declaration: 


dxxRetrieveXML(char() collectionName, /* input */ 
char() resultTabName, /* input */ 


char (30) result_column, /* input */ 
char (30) valid_column, /* input */ 
integer overridelype, /* input */ 
varchar(1024) override, /* input */ 
integer maxRows , /* input */ 
integer numRows , /* output */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 


Example: The following example is of a call to dxxRetrieveXML(). It assumes 
that a result table is created with the name of XML_ORDER_TAB and that the 
table has one column of XMLVARCHAR type. 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 

EXEC SQL BEGIN DECLARE SECTION; 

char collectionName[32]; /* name of an XML collection */ 

char result_tab[32]; /* name of the result table */ 

char result_colname[32]; /* name of the result column */ 

char valid_colname[32]; /* name of the valid column, will set to NULL*/ 


char override[2]; /* override, will set to NULL*/ 
short overrideType; /* defined in dxx.h */ 

short max_row; /* maximum number of rows */ 
short num_row; /* actual number of rows */ 
long returnCode; /* return error code */ 


char returnMsg[1024] ; /* error message text */ 
short collectionName_ind; 

short rtab_ind; 

short rcol_ind; 

short vcol_ind; 

short ovtype_ind; 

short ov_ind; 

short maxrow_ind; 

short numrow_ind; 

short returnCode_ind; 
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short returnMsg_ ind; 
EXEC SQL END DECLARE SECTION; 


/* create table */ 
EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initial host variable and indicators */ 
strcpy(collection, "sales_ord"); 
strcpy(result_tab,"xml_order_tab"); 
strcpy(result_col,"xmlorder") ; 
valid_colname[0] = '\0'; 
override[0] = '\0'; 

overrideType = NO_OVERRIDE; 
max_row = 500; 

num_row = 0; 

returnCode = 0; 

msg_txt[0] = '\0'; 
collectionName_ind = 0; 

rtab_ind = 0; 

rcol_ind = 0; 

vcol_ind = -1; 

ov_ind = -1; 

ovtype_ind = 0; 

maxrow_ind ; 

numrow_ind = -1; 

returnCode_ind = -1; 
returnMsg_ind = -1; 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXRETRIEVE" (:collectionName:collectionName_ind, 
:result_tab:rtab_ind, 
:result_colname:rcol_ind, 
:valid_colname:vcol_ind, 
:overrideType:ovtype_ind, :override:ov_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode:returnCode_ind, 

:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


Related concepts: 


. XM Collections as a storage and access method” on page 105 
- [Mapping schemes for XML collections” on page 125 

- [Using location path with XML collections”-on page 135 

. [Using the DAD file with XML collections” on page 196 


Related tasks: 


* (‘Composing XML collections by using RDB_node mapping” on page 81 
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* |Specifying a stylesheet for an XML collection” on page 134 


. ing an XML collection by using RDB_node mapping 


* |‘Updating, deleting, and retrieving XML collections” on page 121 
* |Searching XML collections” on page 124 


Decomposing XML documents into DB2 data 


To decompose an XML document is to break down the data inside of an XML 
document and store it in relational tables. The XML Extender provides stored 
procedures to decompose XML data from source XML documents into 
relational tables. To use these stored procedures, you must create a DAD file, 
which specifies the mapping between the XML document and DB2 table 
structure. The stored procedures use the DAD file to decompose the XML 
document. 


Enabling an XML collection for decomposition 


In most cases, you need to enable an XML collection before using the stored 
procedures. Cases where you must enable the collections are: 


* When decomposing XML documents into new tables, an XML collection 
must be enabled because all tables in the XML collection are created by the 
XML Extender when the collection is enabled. 


* When keeping the sequence of elements and attributes that have multiple 
occurrence is important. The XML Extender preserves only the sequence 
order of elements or attributes of multiple occurrence for tables that are 
created when a collection is enabled. When XML documents are 
decomposed into existing relational tables, the sequence order is not 
guaranteed to be preserved. 


See the section about the dxxadm administration command for information 
about the enable_collection option. 


If you want to pass the DAD file when the tables already exist in your 
database, you do not need to enable an XML collection. 


Decomposition table size limits 


Decomposition uses RDB_node mapping to specify how an XML document is 
decomposed into DB2 tables by extracting the element and attribute values 
and storing them in table rows. The values from each XML document are 
stored in one or more DB2 tables. Each table can have a maximum of 10240 
rows decomposed from each document. 


For example, if an XML document is decomposed into five tables, each of the 
five tables can have up to 1024 rows for that particular document. If the table 
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has rows for multiple documents, it can have up to 1024 rows for each 
document. If the table has 20 documents, it can have 20,480 rows, 1024 for 
each document. 


Using multiple-occurring elements (elements with location paths that can 
occur more than once in the XML structure) affects the number of rows . For 
example, a document that contains an element <Part> that occurs 20 times, 
might be decomposed as 20 rows in a table. When using multiple occurring 
elements, consider that a maximum of 1024 rows can be decomposed into one 
table from a single document. 


Prerequisites: 


Before you decompose an XML document into DB2 data, perform the 
following steps: 


1. Map the structure of the XML document to the relational tables that 
contain the contents of the elements and attributes values. 


2. Prepare the DAD file, using RDB_node mapping. 
3. Optionally. Enable the XML collection. 


Procedure: 


You use one of the two stored procedures provided by DB2 XML Extender to 
decompose XML documents, dxxShredXML() and dxxInsertXML. 


dxxShredXML() 
This stored procedure is used for applications that do occasional 
updates or for applications that do not want the overhead of 
administering the XML data. The stored procedure dxxShredXML() 
does not required an enabled collection; it uses a DAD file instead. 


The stored procedure dxxShredXML() takes two input parameters, a 
DAD file and the XML document that is to be decomposed; it returns 
two output parameters: a return code and a return message. It inserts 
data from an XML document into an XML collection according to the 
<Xcollection> specification in the input DAD file. The dxxShredXML() 
stored procedure then decomposes the XML document, and inserts 
untagged XML data into the tables specified in the DAD file. The 
tables that are used in the <Xcollection> of the DAD file are assumed 
to exist, and the columns are assumed to meet the data types specified 
in the DAD mapping. If this is not true, an error message is returned. 


The corresponding stored procedure for composition is dxxGenXML\(); 
it also takes the DAD as the input parameter and does not require 
that the XML collection be enabled. 


To decompose an XML collection with dxxShredXML() 
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Embed a stored procedure call in your application using the following 
stored procedure declaration: 


dxxShredXML (CLOB (100K) DAD, /* input */ 
CLOB(1M) xmlobj, /* input */ 
long returnCode, /* output */ 


varchar(1024) returnMsg) /* output «/ 


Example: The following example is a call to dxxShredXML(): 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 
EXEC SQL BEGIN DECLARE SECTION; 
SQL TYPE is CLOB(100K) dad; /* DAD */ 


SQL TYPE is CLOB(100K) xmlDoc; /* input xml document */ 


long returnCode; /* return error code */ 
char returnMsg[1024] ; /* error message text */ 
short dad_ind; 

short xmlDoc_ind; 

short returnCode_ind; 

short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 


FILE *file_handle; 
long file_length=0; 


/* initialize the DAD CLOB object. */ 
file_handle = fopen( "/dxx 
/dad/getstart_xcollection.dad", "r" ); 
if ( file_handle != NULL ) { 
file_length = fread ((void *) &dad.data;, 1, FILE_SIZE, 
file_handle); 
if (file_length == 0) { 
printf ("Error reading dad file getstart_xcollection.dad\n"); 
re = -l; 
goto exit; 
} else 
dad.length = file_length; 
} 


else { 
printf("Error opening dad file \n"); 
re = -l; 
goto exit; 


} 


/* Initialize the XML CLOB object. */ 
file_handle = fopen( "/dxx 
/xml/getstart_xcollection.xml", "r" ); 
if ( file_handle != NULL ) { 
file_length = fread ((void *) &xmlDoc.data;, 1, 
FILE_SIZE, file_handle); 
if (file_length == 0) { 
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printf ("Error reading xml file 
getstart_xcollection.xml \n"); 


re = -1; 
goto exit; 
} else 


xmlDoc. length = file_length; 
} 
else { 
printf("Error opening xml file \n"); 
re = -l; 
goto exit; 


} 


/* initialize host variable and indicators */ 
returnCode = 0; 

msg _txt[0] = '\0'; 

dad_ind = 0; 

xmlDoc_ind = 0; 

returnCode_ind = -1; 

returnMsg_ind = -1; 


/* Call the store procedure «/ 

EXEC SQL CALL "DB2XML.DXXSHRED" (:dad:dad_ind; 
:xm1Doc:xm1Doc_ind, 
:returnCode:returnCode_ind, 
:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


exit: 
return rc; 


dxxInsertXML() 
This stored procedure is used for applications that make regular 
updates. The stored procedure dxxInsertXML() works the same as 
dxxShredXML(), except that dxxInsertXML() takes an enabled XML 
collection as its first input parameter. 


The stored procedure dxxInsertXML() inserts data from an XML 
document into an enabled XML collection, which is associated with a 
DAD file. The DAD file contains specifications for the collection tables 
and the mapping. The collection tables are checked or created 
according to the specifications in the <Xcollection>. The stored 
procedure dxxInsertXML() then decomposes the XML document 
according to the mapping, and it inserts untagged XML data into the 
tables of the named XML collection. 
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The corresponding stored procedure for composition is 
dxxRetrieveXML(); it also takes the name of an enabled XML 
collection. 


To decompose an XML collection: dxxInsertXML() 


Embed a stored procedure call in your application using the following 
stored procedure declaration: 


dxxInsertXML (char ( 
) collectionName, /* input */ 
CLOB(1M) xmlobj, /* input */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 


Example: The following is an example of a call to dxxInsertXML(): 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 

EXEC SQL BEGIN DECLARE SECTION; 

char collectionName[32]; /* name of an XML collection */ 
SQL TYPE is CLOB(100K) xmlDoc; /* input xml document */ 
long returnCode; /* return error code */ 
char returnMsg[1024] ; /* error message text */ 
short  collectionName_ind; 

short xmlDoc_ind; 

short returnCode_ind; 

short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 


FILE *file_handle; 
long file_length=0; 


/* initialize the DAD CLOB object. */ 


file_handle = fopen( "dxxsamples/dad 
/getstart_xcollection.dad", "r" ); 
if ( file_handle != NULL ) { 
file_length = fread ((void *) &dad.data;, 1, FILE_SIZE, 
file_handle); 
if (file_length == 0) { 
printf ("Error reading dad file getstart_xcollection.dad\n"); 
re = -l; 
goto exit; 
} else 
dad. length = file_length; 
} 


else { 
printf("Error opening dad file \n"); 
re = -1; 
goto exit; 


} 


/* initialize host variable and indicators */ 
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strcpy(collectionName, "sales ord"); 
returnCode = 0; 

msg_txt[0] = '\0'; 
collectionName_ind = 0; 

xmlDoc_ind = 0; 

returnCode_ind = -1; 

returnMsg_ind = -1; 


/* Call the store procedure «/ 

EXEC SQL CALL "DB2XML.db2xm1 .DXXINSERTXML" 
(:collection_name:collection_name_ind, 
:xm1Doc:xm1Doc_ind, 
sreturnCode:returnCode_ind, 
:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


exit: 
return rc; 


Related tasks: 
° ing an XML collection by using RDB_node mapping 


84 
* Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* (“XML Extenders decomposition stored procedures” on page 245 


* dxxInsertXML()” on page 248 
* ’dxxShredXML()” on page 245 


Updating, deleting, and retrieving XML collections 


You can update, delete, search, and retrieve XML collections. Remember, 
however, that the purpose of using an XML collection is to store or retrieve 
untagged, pure data in database tables. The data in existing database tables 
has nothing to do with any incoming XML documents; update, delete, and 
search operations consist of normal SQL access to these tables. 


The XML Extender provides the ability to perform operations on the data 
from an XML collection view. Using UPDATE and DELETE SQL statements, 
you can modify the data that is used for composing XML documents, and 
therefore, update the XML collection. 


Restrictions: 
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* Performing SQL operations on the collection tables affects the generated 
documents. 


* To update a document, do not delete a row containing the primary key of 
the table, which is the foreign key row of the other collection tables. When 
the primary key and foreign key row is deleted, the document is deleted. 


* To replace or delete elements and attribute values, you can delete and insert 
rows in lower-level tables without deleting the document. 


* To delete a document, delete the row that composes the top element_node 
specified in the DAD. 


Updating data in an XML collection 


The XML Extender allows you to update untagged data that is stored in XML 
collection tables. By updating XML collection table values, you are updating 
the text of an XML element, or the value of an XML attribute. Additionally, 
updates can delete an instance of data from multiple-occurring elements or 
attributes. 


From an SQL point of view, changing the value of the element or attribute is 
an update operation, and deleting an instance of an element or attribute is a 
delete operation. From an XML point of view, if the element text or attribute 
value of the root element_node exists, the XML document still exists and is, 
therefore, an update operation. SQL operations on collection tables affect 
documents that will be generated from the tables. 


Requirements: When you update data in an XML collection, observe the 
following rules: 


* Specify the primary-foreign key relationship among the collection tables 
when the existing tables have this relationship. If they do not, ensure that 
there are columns that can be joined. 

* Include the join condition that is specified in the DAD file: 

— For SQL mapping, include the join condition in the <SQL_stmt> element. 


— For RDB_node mapping, include the join condition in the top 
<condition> element of the root element node. 


Updating element and attribute values 
In an XML collection, element text and attribute values are all mapped to 


columns in database tables. Regardless of whether the column data previously 
exists or is decomposed from incoming XML documents, you replace the data 
using the normal SQL update technique. 


To update an element or attribute value, specify a WHERE clause in the SQL 
UPDATE statement that contains the join condition that is specified in the 
DAD file. 


Example: 
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UPDATE SHIP_TAB 
set MODE = 'BOAT' 
WHERE MODE='AIR' AND PART_KEY in 
(SELECT PART_KEY from PART_TAB WHERE ORDER_KEY=68) 


The <ShipMode> element value is updated from AIR to BOAT in the 
SHIP_TAB table, where the key is 68. 


Deleting element and attribute instances 

To update composed XML documents by eliminating multiple-occurring 
elements or attributes, delete a row containing the field value that 
corresponds to the element or attribute value, using the WHERE clause. As 
long as you do not delete the row that contains the values for the top 
element_node, deleting element values is considered an update of the XML 
document. 


For example, in the following DELETE statement, you are deleting a 
<shipment> element by specifying a unique value of one of its sub-elements. 


DELETE from SHIP_TAB 
WHERE DATE='1999-04-12' 


Specifying a DATE value deletes the row that matches this value. The 
composed document originally contained two <shipment> elements, but now 
contains one. 


Deleting an XML document from an XML collection 


You can delete an XML document that is composed from a collection. This 
means that if you have an XML collection that composes multiple XML 
documents, you can delete one of these composed documents. Performing 
SQL operations on the collection tables affects the generated documents. 


To delete the document, delete a row in the table that composes the top 
element_node that is specified in the DAD file. This table contains the 
primary key for the top-level collection table and the foreign key for the 
lower-level tables. Deleting the document with this method works only if the 
primary-key/foreign-key constraints are fully specified in the SQL and if the 
relationship of the tables shown in the DAD match those constraints exactly. 


Example: 


The following DELETE statement specifies the value of the primary key 
column. 


DELETE from order_tab 
WHERE order_key=1 


ORDER_KEY is the primary key in the table ORDER_TAB, which is the 
top-level table as specified in the DAD. Deleting this row deletes one XML 
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document that is generated during composition. Therefore, from the XML 
point of view, one XML document is deleted from the XML collection. 


Retrieving XML documents from an XML collection 


Retrieving XML documents from an XML collection is similar to composing 
documents from the collection. 


DAD file consideration: When you decompose XML documents in an XML 
collection, you can lose the order of multiple-occurring elements and attribute 
values, unless you specify the order in the DAD file. To preserve this order, 
you should use the RDB_node mapping scheme. This mapping scheme allows 
you to specify an orderBy attribute for the table containing the root element in 
its RDB_node. 


Searching XML collections 


This section describes searching an XML collection in terms of generating 
XML documents using search criteria, and searching for decomposed XML 
data. 


Generating XML documents using search criteria 


This task is the same as composition using a condition. You can specify the 
search criteria using the following search criteria: 


* Specify the condition in the text_node and attribute_node of the DAD file 


* Specify the overwrite parameter when using the dxxGenXML() and 
dxxRetrieveXML() stored procedures. 


For example, if you enabled an XML collection, sales_ord, using the DAD 
file, order.dad, but you now want to override the price using form data 
derived from the Web, you can override the value of the <SQL_stmt> DAD 
element, as follows: 


EXEC SQL INCLUDE SQLCA; 
EXEC SQL BEGIN DECLARE SECTION; 


EXEC SQL END DECLARE SECTION; 
float price_value; 


/* create table */ 
EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initialize host variable and indicators */ 
strcpy(collection,"sales_ord"); 
strcpy(result_tab,"xml_order_tab"); 
overrideType = SQL_OVERRIDE; 

max_row = 20; 
num_row = 0; 
returnCode = 0; 
msg_txt[0] '\O'; 
override_ind = 0; 


124 Administration and Programming for iSeries 


overrideType_ind = 0; 


rtab_ind = 0; 
maxrow_ind = 0; 
numrow_ind = -1; 


returnCode_ind = -1; 
returnMsg_ind = -1; 


/* get the price_value from some place, such as form data */ 
price_value = 1000.00 /* for examplex/ 


/* specify the overwrite «/ 
sprintf (overwrite, 
"SELECT o.order_key, customer, p.part_key, quantity, price, 
tax, ship_id, date, mode 
FROM order_tab o, part_tab p, 


(select db2xml.generate_unique() 
as ship_id, date, mode from ship_tab) as s 
WHERE p.price > %d and s.date >'1996-06-01' AND 
p.order_key = o.order_key and s.part_key = p.part_key", 
price_value); 


/* Call the store procedure «/ 

EXEC SQL CALL db2xml!dxxRetrieve(:collection:collection_ind, 
:result_tab:rtab_ind, 
:overrideType:overridelType_ind, :overwrite:overwrite_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode: returnCode_ind,:returnMsg:returnMsg_ ind); 


The condition of price > 2500.00 in order.dad is overridden by price > ?, 
where ? is based on the input variable price_value. 


Searching for decomposed XML data 


You can use normal SQL query operations to search collection tables. You can 
join collection tables, or use subqueries, and then do a structural-text search 
on text columns. Apply the results of the structural search to retrieve or 
generate the specified XML document. 


Mapping schemes for XML collections 
If you are using an XML collection, you must select a mapping scheme, which 


specifies how XML data is represented in a relational database. Because XML 
collections must match the hierarchical structure of XML documents with a 


relational structure for relational databases, you should understand how the 
two structures compare.|Figure 11 on page 126|shows how the hierarchical 


structure can be mapped to relational table columns. 
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Figure 11. XML document structured mapped to relational table columns 


ShipDate ShipMode 
text_node text_node 
date mode 


The XML Extender uses a mapping scheme when composing or decomposing 
XML documents that are located in multiple relational tables. The XML 
Extender provides a wizard that assists you in creating the DAD file. 
However, before you create the DAD file, you must think about how your 
XML data is mapped to the XML collection. 


Types of mapping schemes: 


Use <Xcollection> to specify the mapping scheme in the DAD file. The XML 

Extender provides two types of mapping schemes: SQL mapping and. Relational 
Database (RDB_node) mapping. Both methods use the XPath model to define the 
hierarchy of the XML document. 
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SQL mapping 
This method allows direct mapping from relational data to XML 
documents through a single SQL statement. SQL mapping is used for 
composition only. The content of the <SQL_stmt> element must be a 
valid SQL statement. The <SQL_stmt> element specifies columns in 
the SELECT clause that are mapped to XML elements or attributes 
later in the DAD. When defined for composing XML documents, the 
column names in the SELECT clause of the SOL statement are used to 
associate the value of an attribute_node or a content of text_node with 
columns that have the same name_attribute. The FROM clause defines 
the tables containing the data; the WHERE clause specifies the join 
and search condition. 


SQL mapping gives DB2® users the power to map the data using 
SQL. When using SQL mapping, you must be able to join all tables in 
one SELECT statement to form a query. If one SQL statement is not 
sufficient, consider using RDB_node mapping. To tie all tables 
together, the primary key and foreign key relationship is recommended 
among these tables. 


RDB_node mapping 
Defines the location of the content of an XML element or the value of 
an XML attribute so that the XML Extender can determine where to 
store or retrieve the XML data. 


This method uses the XML Extender-provided RDB_node, which 
contains one or more node definitions for tables, optional columns, 
and optional conditions. The <table> and <column> elements in the 
DAD define how the XML data is to be stored in the database. The 
condition specifies the criteria for selecting XML data or the way to 
join the XML collection tables. 


To define a mapping scheme, you must create a DAD file with an 
<Xcollection> element. Figure 12 on page 128]shows a fragment of a sample 
DAD file with SQL mapping for an XML collection, which composes a set of 
XML documents from data in three relational tables. 
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<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "dxx_install/samples/db2xml/dtd/dad.dtd"> 
<DAD> 
<dtdid>dxxsamples/dad/getstart.dtd</dtdid> 
<validation>YES</validation> 
<Xcollection> 
<SQL_stmt> 
SELECT o.order_key, customer, p.part_key, quantity, price, tax, date, 
ship_id, mode, comment 
FROM order_tab o, part_tab p, 
(select db2xml.generate_unique() 
as ship_id, date, mode, from ship_tab) as 
WHERE p.price > 2500.00 and s.date > "1996-06-01" AND 
p.order_key = o.order_key and s.part_key = p.part_key 
</SQL_stmt> 
<prolog>?xml version="1.0"?</prolog> 
<doctype>!DOCTYPE DAD SYSTEM 


dxxsamples/dtd/getstart.dtd"</doctype> 
<root_node> 
<element_node name="O0rder"> 
<attribute_node name="key"> 
<column name="order_key"/> 
</attribute_node> 
<element_node name="Customer"> 
<text_node> 
<column name="customer"/> 
</text_node> 
<element_node> 


</element_node><!-end Part-> 
</element_node><!-end Order-> 
</root_node> 
</Xcollection> 
</DAD> 
Figure 12. SQL mapping scheme 


The XML Extender provides several stored procedures that manage data in an 
XML collection. These stored procedures support both types of mapping. 


Related concepts: 


* |“Using the DAD file with XML collections” on page 196 
* {Requirements for RDB_Node mapping” on page 131 


Related tasks: 
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* {Decomposing an XML collection by using RDB_node mapping” on page 


Requirements for using SQL mapping 
Requirements when using SQL mapping 


In this mapping scheme, you must specify the <SQL_stmt> element 
inside the DAD <Xcollection> element. The <SQL_stmt> must contain 
a single SQL statement that can join multiple relational tables with the 
query predicate. In addition, the following clauses are required: 


¢ SELECT clause 


— Ensure that the name of the column is unique. If two tables have 
the same column name, use the AS keyword to create an alias 
name for one of them. 


— Group columns of the same table together and order the tables 
according to the tree level as they map to the hierarchical 
structure of your XML document. The first column in each 
column grouping is an object ID. In the SELECT clause, the 
columns of the higher-level tables must precede the columns of 
lower-level tables. The following example demonstrates the 
hierarchical relationship among tables: 


SELECT o.order_key, customer, p.part_key, quantity, price, tax, 
ship_id, date, mode 


In this example, the order_key and customer columns from the 
ORDER_TAB table have the highest relational level because they 
are higher on the hierarchical tree of the XML document. The 
ship_id, date, and mode columns from the SHIP_TAB table are at 
the lowest relational level. 


— Use a single-column candidate key to begin each level. If such a 
key is not available in a table, the query should generate one for 
that table using a table expression and the 
generate_unique()user-defined function. In the above example, 
the o.order_key is the primary key for ORDER_TAB, and the 
part_key is the primary key of PART_TAB. They appear at the 
beginning of their own group of columns that are to be selected. 
The ship_id is generated as a primary key because the 
SHIP_TAB table does not have a primary key. ship_id is listed as 
the first column for the SHIP_TAB table group. Use the FROM 
clause to generate the primary key column, as shown in the 
following example. 


* FROM clause 
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Use a table expression and the generate_unique()user-defined 
function to generate a single key for tables that do not have a 
primary single key. For example: 
FROM order_tab as 0, part_tab as p, 

(select 


db2xml.generate_unique() as 
ship_id, date, mode, part key from ship_tab) as s 


In this example, a single column candidate key is generated with 
the generate_unique() function and given an alias named 
ship_id. 

Use an alias name when it is necessary to make a column 
distinct. For example, you could use o for columns in the 
ORDER_TAB table, p for columns in the PART_TAB table, and s 
for columns in the SHIP_TAB table. 


¢ WHERE clause 


Specify a primary and foreign key relationship as the join 
condition that ties tables in the collection together. For example: 
WHERE p.price > 2500.00 AND s.date > "1996-06-01" AND 

p.order_key = o.order_key AND s.part_key = p.part_key 
Specify any other search condition in the predicate. Any valid 
predicate can be used. 


¢ ORDER BY clause 


Define the ORDER BY clause at the end of the SQL_stmt. Ensure 
that there is nothing after the column names such as ASC or 
DESC. 


Ensure that the column names match the column names in the 
SELECT clause. 


List all object ID’s in the same relative order as they appear in 
the SELECT clause. 


An identifier can be generated using a table expression and the 
generate_unique() function or a user defined function. 

Maintain the top-down order of the hierarchy of the entities. The 
first column specified in the ORDER BY clause must be the first 
column listed for each entity. Keeping the order ensures that the 
XML documents to be generated do not contain incorrect 
duplicates. 

Do not qualify the columns in the ORDER BY clause with a 
schema or table name. 


The <SQL_stmt> element is powerful because you can specify any 
predicate in your WHERE clause, as long as the expression in the 
predicate uses the columns in the tables. 
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Related reference: 


* |Appendix A, “Samples” on page 281 


Requirements for RDB_Node mapping 


When using RDB_Node as your mapping method, do not use the 
<SQL_stmt>element in the <Xcollection> element of the DAD file. Instead, use 
the <RDB_node> element in each of the top nodes for the element node and 
for each attribute node and text node. 


* RDB_node for the top element_node 


The top element_node in the DAD file represents the root element of the 
XML document. Specify an RDB_node for the top element_node as follows: 


— Specify all tables that are associated with the XML collection. For 
example, the following mapping specifies three tables in the 
<RDB_node> of the<Order> element node, which is the top element 
node: 
<element_node name="Order"> 

<RDB_node> 
<table name="order_tab"/> 
<table name="part_tab"/> 
<table name="ship_tab"/> 
<condition> 
order_tab.order_key = part_tab.order_key AND 
part_tab.part_key = ship_tab.part_key 
</condition> 
</RDB_node> 


The condition element can be empty or missing if there is only one table 
in the collection. 


— Condition elements can reference a column name an unlimited number 
of times. 


— If you are decomposing, or enabling, the XML collection specified by the 
DAD file, you must specify a primary key for each table. The primary 
key can consist of a single column or multiple columns, called a 
composite key. Specify the primary key by adding an attribute key to the 
table element of the RDB_node. When you supply a composite key, the 
key attribute will be specified by the names of key columns separated by 
a space. For example: 


<table name="part_tab" key="part_key price"/> 


The information specified for decomposition is ignored if the same DAD 
is used for composition. 

— Use the orderBy attribute to reeompose XML documents containing 
elements or attributes with multiple occurrence back to their original 
structure. This attribute allows you to specify the name of a column that 
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will be the key used to preserve the order of the document. The orderBy 
attribute is part of the table element in the DAD file, and it is an 
optional attribute. 


Spell out the table name and the column name in the <table>tag. 
* RDB_node for each attribute_node and text_node 


The XML Extender needs to know from where in the database to retrieve 
the data. XML Extender also needs to know where in the database to put 
the content from an XML document. You must specify an RDB_node for 
each attribute node and text node. You must also specify the table and 
column names; the condition value is optional. 


1. Specify the name of the table containing the column data. The table 
name must be included in the RDB_node of the top element_node. In 
this example, for text_node of element <Price>, the table is specified as 
PART_TAB. 
<element_node name="Price"> 

<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="price"/> 
<condition> 
price > 2500.00 
</condition> 
</RDB_node> 
</text_node> 
</element_node> 

2. Specify the name of the column that contains the data for the element 

text. In the previous example, the column is specified as PRICE. 


3. Specify a query condition if you want XML documents to be generated 
using that condition. Only the data meeting the condition is in the 
generated XML documents. The condition must be a valid WHERE 
clause. In the example above, the condition is specified as price > 
2500.00, so only rows where the price is over 2500 will be included in 
the XML documents. 


4. If you are decomposing a document, or enabling the XML collection 
specified by the DAD file, you must specify the column type for each 
attribute node and text node. By specifying the column type for each 
attribute node and text node, you ensure that he correct data type for 
each column when new tables are created during the enabling of an 
XML collection. Column types are specified by adding the attribute type 
to the column element. For example: 


<column name="order_key" type="integer"/> 


The column type specified when decomposing a document is ignored 
for composition. 
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Maintain the top-down order of the hierarchy of the entities. Ensure that 
the element nodes are nested properly so that the XML Extender 
understands the relationship between the elements when composing or 
decomposing documents. For example, the following DAD file does not 
nest Shipment inside of Part: 


<element_node name="Part"> 
<element_node name="ExtendedPrice"> 
</element_node> 

</element_node> <!-- end of element Part --> 


<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 


</element_node> 
<element_node name="ShipMode"> 


</element_node> 
</element_node> <!-- end of element Shipment--> 


This DAD file produces an XML documents in which the Part and 
Shipment elements are siblings. 
<Part color="black "> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850. 16</ExtendedPrice> 
<Tax>6 .000000e-2</Tax> 
</Part> 


<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 


<ShipMode>BOAT </ShipMode> 
</Shipment> 


The following code shows the shipment element nested inside the Part 
element in the DAD file. 


<element_node name="Part"> 
<element_node name="ExtendedPrice"> 
</element_node> 


<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 


</element_node> 
<element_node name="ShipMode"> 
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</element_node> 


</element_node> <!-- end of element Shipment--> 
</element_node> <!-- end of element Part --> 


Nesting the shipment element inside the part element produces an XML file 
with Shipment as a child element of the Part element: 


<Part color="black "> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850. 16</ExtendedPrice> 
<Tax>6 .000000e-2</Tax> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>BOAT </ShipMode> 
</Shipment> 
</Part> 


There are no ordering restrictions on predicates of the root node condition. 
With the RDB_node mapping approach, you don’t need to supply SQL 


statements. However, putting complex query conditions in the RDB_node 
element can be more difficult. 


Specifying a stylesheet for an XML collection 


When composing documents, the XML Extender also supports processing 
instructions for stylesheets, using the <stylesheet> element. The processing 
instructions must be inside the <Xcollection> root element, located with the 
<doctype> and <prolog> defined for the XML document structure. For 
example: 

<?xml version="1.0"?> 

<!DOCTYPE DAD SYSTEM "c:\dtd\dad.dtd"> 

<DAD> 

<SQL_stmt> 


</SQL_stmt> 
<Xcollection> 


<prolog>...</prolog> 

<doctype>...</doctype> 

<stylesheet>?xml-stylesheet type="text/css" href="order.css"?</stylesheet> 
<root_node>...</root_node> 


</Xcollection> 


</DAD> 
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Using location path with XML collections 


A location path defines the location of an XML element or attribute within the 
structure of the XML document. The XML Extender uses the location path for 
the following purposes: 


* To locate the elements and attributes to be extracted when using extraction 
UDFs such as dxxRetrieveXML. 


* To specify the mapping between an XML element or attribute and a DB2® 
column when defining the indexing scheme in the DAD for XML columns 


* For structural text search, using the Text Extender 
* To override the XML collection DAD file values in a stored procedure. 


Figure 13}shows an example of a location path and its relationship to the 
structure of the XML document. 


Order 


<key > Customer Part 


Name Email 


| I 


(American Motors) ( parts@am.com ) 
<Coior> Key ois ExtendedPrice Shipment 


(black ) EE Ew ( 34,850.16) a 


ShipDate ShipMode 


Location path: “/Order/Part/Shipment/ShipDate”.---------.-~ 1998-08-19 


Figure 13. Storing documents as structured XML documents in a DB2 table column 


Related reference: 


* Working with an XML Extender location path” on page 135 


Working with an XML Extender location path 


XML Extender uses the location path to navigate the XML document 
structure. The following list describes the location path syntax that is 
supported by the XML Extender. A single slash (/) path indicates that the 
context is the whole document. 
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L/ Represents the XML root element. This the element that contains all 
the other elements in the document. 


2. /tag1 
Represents the element tag] under the root element. 


3. /tagl/tag2/..../tagn 
Represents an element with the name tagn as the child of the 
descending chain from root, tag1, tag2, through tagn-1. 


4. //tagn 
Represents any element with the name tagn, where double slashes 
(//) denote zero or more arbitrary tags. 


5. /tag1//tagn 
Represents any element with the name tagn, a descendent of an 
element with the name tag] under root, where double slashes (//) 
denote zero or more arbitrary tags. 


6. /tag1/tag2/@attr1 
Represents the attribute attr1 of an element with the name tag2, which 
is a child of element tag] under root. 


7. /tag1/tag2[@attr1="5"] 
Represents an element with the name tag2 whose attribute attr1 has 
the value 5. Thetag2 is a child of the taglelement under root. 


8. /tag1/tag2[@attr1="5" ]/.../tagn 
Represents an element with the name tagn, which is a child of the 
descending chain from root, tag1, tag2, through tagn-1, where the 
attribute attr1 of tag2 has the value 5. 


Simple location path 


Simple location path is a type of location path used in the XML column 
DAD file. A simple location path is represented as a sequence of 
element-type names that are connected by a single slash (/). The 
values of each attribute are enclosed within square brackets following 


the element type. |Table 17/summarizes the syntax for simple location 


path. 
Table 17. Simple location path syntax 
Subject Location path Description 
XML element /tag1/tag2/..../tagn-1/tagn An element content identified by 
the element named tagn and its 
parents 


XML attribute /tag_1/tag_2/..../tag_n-1/tag_n/@attr1 | An attribute namedattr1 of the 
element identified by tagn and 
its parents 
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Location path usage 


The syntax of the location path is dependent on the context in which 
you are accessing the location of an element or attribute. Because the 
XML Extender uses one-to-one mapping between an element or 
attribute, and a DB2 column, it restricts the syntax rules for the DAD 
file and functions. [Table 18] describes in which contexts the syntax 
options are used. 


Table 18. The XML Extender’s restrictions using location path 


Use of the location path Location path supported 

Value of path attribute in the XML column | 3, 6 (simple location path described in 

DAD mapping for side tables Table 17 on page 136 

Extracting UDFs 1-81 

Update UDF 1-81 

Text Extender’s search UDF 3 — Exception: the root mark is specified 
without the slash. For example: 
tagl/tag2/..../tagn 


1 The extracting and updating UDFs support location paths that have predicates with 
attributes, but not elements. 


Related concepts: 


* {Using location path with XML collections” on page 135 


Enabling XML Collections 


Enabling an XML collection parses the DAD file to identify the tables and 
columns related to the XML document, and records control information in the 
XML_USAGE table. Enabling an XML collection is optional for: 


* Decomposing an XML document and storing the data in new DB2 tables 
* Composing an XML document from existing data in multiple DB2 tables 


If the same DAD file is used for composing and decomposing, you can enable 
the collection for both composition and decomposition. 


You can enable an XML collection through the XML Extender administration 
wizard, using the dxxadm command with the enable_collection option, or you 
can use the XML Extender stored procedure dxxEnableCollection(). 


Using the administration wizard: 


Use the following steps to enable an XML collection using the wizard: 
1. Set up and start the administration wizard. 
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2. Click Work with XML Collections from the LaunchPad window. The 
Select a Task window opens. 


3. Click Enable a Collection and then Next. The Enable a Collection window 
opens. 


4. Select the name of the collection you want to enable in the Collection 
name field from the pull-down menu. 


5. Type the DAD file name in the DAD file name field or click ... to browse 
for an existing DAD file. 


6. Optionally, type the name of a previously created table space in the Table 
space field. 


The table space will contain new DB2 tables generated for decomposition. 
7. Click Finish to enable the collection and return to the LaunchPad window. 


* If the collection is successfully enabled, an Enabled collection is 
successful message is displayed. 


* If the collection is not successfully enabled, an error message is 
displayed. Repeat the preceding steps until the collection is successfully 
enabled. 


Enabling collections using the dxxadm command: 


To enable an XML collection, enter the dxxadm command from a DB2 
command line: 


Syntax: 


>>—dxxadm—enable_collection—dbName—collection—DAD_file >< 


Parameters: 


dbName 
The name of the RDB database. 


collection 
The name of the XML collection. This value is used as a parameter for 
the XML collection stored procedures. 


DAD_file 
The name of the file that contains the document access definition 
(DAD). 


tablespace 
An existing table space that contains new DB2 tables that were 
generated for decomposition. If not specified, the default table space is 
used. 
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Example: The following example enables a collection called sales_ord in the 
database SALES_DB using the command line. The DAD file uses SQL 


mapping. 
From the Qshell: 
dxxadm enable_collection SALES DB sales_ord getstart_collection.dad 


From the OS command line: 


CALL QDBXM/QZXMADM PARM(enable_collection SALES_DB sales_ord 
'getstart_collection.dad') 


From the Operations Navigator: 


CALL MYSCHEMA.QZXMADM('enable_collection', ‘SALES DB', ‘sales ord', 
‘getstart_collection.dad'); 


After you enable the XML collection, you can compose or decompose XML 
documents using the XML Extender stored procedures. 


Related concepts: 


* “XML Collections as a storage and access method” on page 109 


Related tasks: 


* “Disabling XML collections” on page 139 
* (“Managing data in XML collections” on page 110 


Disabling XML collections 


Disabling an XML collection removes the record in the XML_USAGE table 
that identify tables and columns as part of a collection. It does not drop any 
data tables. You disable a collection when you want to update the DAD and 
need to re-enable a collection, or to drop a collection. 


You can disable an XML collection through the XML Extender administration 
wizard, using the dxxadm command with the disable_collection option, or 
using the XML Extender stored procedure dxxDisableCollection(). 


Procedure: 


To disable an XML collection using the administration wizard: 
1. Set up and start the administration wizard. 


2. Click Work with XML Collections from the LaunchPad window to view 
the XML Extender collection related tasks. The Select a Task window 
opens. 
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3. Click Disable an XML Collection and then Next to disable an XML 
collection. The Disable a Collection window opens. 


4. Type the name of the collection you want to disable in the Collection 
name field. 


5. Click Finish to disable the collection and return to the LaunchPad 
window. 


* If the collection is successfully disabled, an Disabled collection is 
successful message is displayed. 


* If the collection is not successfully disabled, an error box is displayed. 
Continue the preceding steps until the collection is successfully disabled. 


To disable an XML collection from the command line, enter the dxxadm 
command. 


Syntax: 


>>—dxxadm—disable_collection—dbName—collection >< 


Parameters: 


dbName 
The name of the RDB database. 


collection 
The name of the XML collection. This value is used as a parameter for 
the XML collection stored procedures. 


Example: 


From the Qshell: 
dxxadm disable_collection SALES _DB sales ord 


From the OS command line: 
CALL QDBXM/QZXMADM PARM(disable_ collection SALES DB sales_ord) 


From the Operations Navigator: 
CALL MYSCHEMA.QZXMADM('disable_collection', ‘SALES DB', ‘sales ord'); 


Related concepts: 


* “XML Collections as a storage and access method” on page 109 


Related tasks: 


* |’Managing data in XML collections” on page 110 
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Related reference: 


* (XML Extender administration stored procedures” on page 224 
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Chapter 5. XML Schemas 


The XML Schema can be used in place of a DTD to define the specifications 
for the content of XML documents. The XML schema uses XML format or 
SML syntax to define the elements and attribute names of an XML document, 
and defines the type of content the elements and attributes are allowed to 
contain. 


Advantages of using XML schemas 


DTDs are easier to code and validate than an XML Schema. However, there 

are several advantages to using an XML schema, as shown in the following 

list: 

* XML schemas are valid XML documents that can be processed by tools 
such as the XSD Editor in WebSphere® Studio Application Developer, XML 
Spy, or XML Authority. 


* XML schemas are more powerful than DTDs. Everything that can be 
defined by DTD can also be defined by schemas, but not vice versa. 

* XML Schemas support a set of data types, similar to the ones used in most 
common programming languages, and provide the ability to create 
additional types. You can constrain the document content to the appropriate 
type. For example, you can replicate the properties of fields found in DB2. 

* XML schema supports regular expressions to set constraints on character 
data, which is not possible if you use a DTD. 

* XML schemas provide better support for XML namespaces, which enable 
you to validate documents that use multiple namespaces, and to reuse 
constructs from schemas already defined in different namespaces. 

* XML schemas provide better support for modularity and reuse with include 
and import elements. 

* XML schemas support inheritance for element, attribute and data type 
definitions. 


Related tasks: 


* {Declaring data types and elements in schemas” on page 145 


Related reference: 


* |‘Example of an XML schema” on page 146 


© Copyright IBM Corp. 1999, 2003 143 


User-defined types and user-defined function names for XML Extender 


The full name of a DB2® function is schema-name.function-name, where 
schema-name is an identifier that provides a logical grouping for a set of SQL 
objects. The schema name for XML Extender UDFs and UDTs is DB2XML. In 
the documentation, references are made only to the function name. 


You can specify UDTs and UDFs without the schema name if you add the 
schema name to the function path. The function path is an ordered list of 
schema names. DB2 uses the order of schema names in the list to resolve 
references to functions and UDTs. You can specify the function path by 
specifying the SQL statement SET CURRENT FUNCTION PATH. This 
statement sets the function path in the CURRENT FUNCTION PATH special 
register. 


XML schema complexType element 


The XML schema element complexType is used to define an element type that 
can consist of sub-elements. For example, the following tags show the 
projection of an address in an XML document: 


<billTo country="US"> 
<name>Dan Jones</name> 
<street>My Street</street> 
<city>My Town</city> 
<state>CA</state> 
<zip>99999</zip> 

</billTo> 


The structure of this element can be defined in XML Schema as follows: 


1 <xsd:element name="billTo" type="USAddress"/> 
2 < xsd:complexType name="USAddress"> 
3 <xsd:sequence> 
4 <xsd:element name="name" type="xsd:string"/> 
5 <xsd:element name="street" type="xsd:string"/> 
6 <xsd:element name="city" type="xsd:string"/> 
7 <xsd:element name="state" type="xsd:string"/> 
8 <xsd:element name="zip" type="xsd:decimal"/> 
9 </xsd:sequence> 
10 < xsd:attribute name="country" 
type="xsd:NMTOKEN" use="fixed" 
value="US"/> 
12</xsd: comp] exType> 


In the above example, it is assumed that the xsd prefix has been bound to the 
XML Schema namespace. Lines 2 through 5 define the complexType 
USAddress as a sequence of five elements and one attribute. The order of the 
elements is determined by the order in which they appear in the sequence tag. 
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The inner elements are from data type xsd:string or xsd:decimal. Both are 
predefined simple data types. 


Alternatively, you can use the all tag or the choice tag instead of the sequence 
tag. With the all tag, all sub-elements must appear, but do not need to appear 
in any particular order. With the choice tag, exactly one of the sub-elements 
must appear in the XML document 


You can also use a user-defined data type to define other elements. 


Declaring data types and elements in schemas 


Declaring simple data types 


XML schemas provide a set of simple build-in data types. You can derive 
other data types from them by applying constraints. 


In Example 1, the range of base type xsd-:positivelnteger is limited to 0 to 100. 


Example 1 
< xsd:element name="quantity"> 
< xsd:simpleType> 
< xsd:restriction base="xsd:positiveInteger"> 
< xsd:maxExclusive value="100"/> 
</xsd:restriction> 
</xsd:simpleType> 
</xsd:element> 


In Example 2, the base type xsd:string is limited by a regular expression. 


Example 2 
<xsd:simpleType name="SKU"> 
< xsd:restriction base="xsd:string"> 
< xsd:pattern value="\d{3}-[A-Z] {2}"/> 
</xsd:restriction> 
</xsd:simpleType> 


Example 3 shows an enumerated type based on the string built-in type. 


Example 3 
<xsd:simpleType name="SchoolClass"> 

< xsd:restriction base="xsd:string"> 
xsd:enumeration value="WI"/> 
xsd:enumeration value="MI"/> 
xsd:enumeration value="II"/> 
xsd:enumeration value="DI"/> 

< xsd:enumeration value="AI"/> 
</xsd:restriction> 
</xsd:simpleType> 


AAA AN 
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Declaring elements 


To declare an element in an XML schema you must indicate the name and 
type as an attribute of the element element. For example: 


<xsd:element name="street" type="xsd:string"/> 


Additionally, you can use the attributes minOccurs and maxOccurs to 
determine the maximum or minimum number of times that the element must 
appear in the XML document. The default value of minOccurs and maxOccurs 
is 1. 

Declaring attributes 


Attribute declarations appear at the end of an element definition. For 
example: 


<:xsd:complexType name="PurchaseOrderType"> 

< xsd:element name="billTo" type="USAddress"/> 

< xsd:attribute name="orderDate" type="xsd:date"/> 
</xsd:comp]exType> 


Related concepts: 


* |“Advantages of using XML schemas” on page 143 


Related tasks: 


* |“Validation functions” on page 190 


Related reference: 


* “Example of an XML schema” on page 146 


* |“XML schema complexType element” on page 144 


Example of an XML schema 


It is a good strategy to write XML schemas by first designing the data 
structure of your XML document using a UML tool. After you design the 
structure, you can map the structure into your schema document. The 
following example shows an XML schema. 


1 <?xml version="1.0" encoding="UTF-8"?> 
2 <xs:schema xmins:xs='http://www.w3.org/2001/XMLSchema '> 


3 

4 <xs:element name="personnel "> 

5 <xs:complexType> 

6 <xs : Sequence> 

7 <xs:element ref="person" minOccurs='1' maxOccurs='unbounded'/> 
8 </xs:sequence> 

9  </xs:complexType> 

10 </xs:element> 

11 
12 


<xs:element name="person"> 
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The first 2 lines declare that this XML schema is XML 1.0 compatible and 


13 <xs:complexType> 


14 <xS:sequence> 

15 <xs:element ref="name"/> 

16 <xs:element ref="email" minOccurs='0' maxOccurs='4'/> 
17 </xs:sequence> 

18 <xs:attribute name="id" type="xs:ID" use='required'/> 


19 </xs:complexType> 
20 </xs:element> 


22 <xs:element name="name"> 
23 <xs:comp]lexType> 


24 <xs:sequence> 
25 <xs:element ref="family"/> 
26 <xs:element ref="given"/> 


27 </xs:Sequence> 
28 =</xs:complexType> 
29 </xs:element> 


31 <xs:element name="family" type='xs:string'/> 
32 <xs:element name="given" type='xs:string'/> 
33 <xs:element name="email" type='xs:string'/> 
34 </xs:schema> 


Unicode 8 decoded, and specify use of the XML schema standard namespace, 
which enables access to basic XML schema data types and structures. 


Lines 4 to 10 define the personnel as a complexType that consists of a 
sequence of 1 to n persons. The complexType is then defined in lines 12 to 20. 


It consists of the complexType element name and the element e-mail. The 


email element is optional (minOcccurs = ’0’), and can appear up to four times 
(maxOccurs = ’4’). The greater the number of occurrences of an element, the 
longer it will take to validate the schema. In contrast, in a DTD you can 
choose only 0, 1, or unlimited appearances of an element. 


Lines 22 to 29 define the name type that is used for the person type. The 
name type consists of a sequence of a family and a given element. 


Lines 31 to 33 define the single elements family, given, and e-mail, which 
contain type strings that have been declared. 


XML document instance using the schema 


The following example is an XML document that is an instance of the 
personalnr.xsd schema. 


1 <?xml version="1.0" encoding="UTF-8"?> 
2 <personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 


3 


4 
5 
6 
7 


xsi:noNamespaceSchemaLocation='personsnr.xsd'> 
<person id="Big.Boss" > 


<name><fami ly>Boss</family> <given>Big</given></name> 
<email>chief@foo.com</emai1> 
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8  </person> 


10 <person id="one.worker"> 
11 <name><fami1ly>Worker</fami 1 y><gi ven>One</given></name> 


12 <emai 1>one@foo.com</emai 1> 
13. </person> 
14 


15 <person id="two.worker"> 

16 <name><family>Worker</fami 1 y><gi ven>Two</given></name> 
17 <emai 1>two@foo.com</emai1> 

18  </person> 

19 </personnel> 


XML document instance using a DTD 
This example shows how this XML schema would be realized as a DTD. 


<?xml version="1.0" encoding="UTF-8"?> 
<!ELEMENT email (#PCDATA)> 

<!ELEMENT family (#PCDATA)> 

<!ELEMENT given (#PCDATA)> 

<!ELEMENT name (family, given)> 
<!ELEMENT person (name, email*)> 


OANA NHB WNHHE 


<!ATTLIST person 
9 id ID #REQUIRED> 
10 <!ELEMENT personnel (person+)> 


Using a DTD we cannot set the maximum occurrence of email to values other 
than, 1 or unlimited occurrences. 


Using this DTD, the XML document instance would be the same as shown in 
the previous section, except line 2 would be changed to: 


<!DOCTYPE personnel SYSTEM "personsnr.dtd"> 


Related concepts: 


* |“Advantages of using XML schemas” on page 143 


Related tasks: 


* {Declaring data types and elements in schemas” on page 145 
* Validation functions” on page 190 


Related reference: 
* “XML schema complexType element” on page 144 
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Chapter 6. The dxxadm administration command 


Purpose of the administration command 


The XML Extender provides an administration command, dxxadm, for 
completing the following administration tasks from the Q-shell or the OS 
command line. 


* Enabling or disabling a database for the XML Extender 
* Enabling or disabling an XML column 
* Enabling or disabling an XML collection 


Related concepts: 


Administration Tools” on page 41 
XML Extender administration planning” on page 51 


administration command 
The following dxxadm are available to system programmers: 
* enable_column 
* enabale_collection 
* enable_db 
* disable_column 
* disable_collection 
* disable_db 


enable_db option 
Purpose: 


Enables XML Extender features for a database. When the database is enabled, 
the XML Extender creates the following objects: 


* The XML Extender user-defined types (UDTs). 
* The XML Extender user-defined functions (UDFs). 


¢ The XML Extender DTD reference table, DTD_REF, which stores DTDs and 
information about each DTD. 


* The XML Extender usage table, XML_USAGE, which stores common 
information for each column that is enabled for XML and for each 
collection. 
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Syntax: 


>>—dxxadm—enab] ee Il hccescuat 4«~*~«7«<S<;«7«<S Ce 
-]1—login -p—pas sword: 


Parameters: 


Table 19. enable_db parameters 


Parameter Description 


db_name The name of the RDB database in which 
the XML data resides. 


-] login The user ID, which is optional, used to 
connect to the database, when specified. If 
not specified, the current user ID is used. 


-p password The password, which is optional, used to 
connect to the database, when specified. If 
not specified, the current password is 
used. 


Examples: 
The following example enables the database SALES_DB. 


From the Qshell: 
dxxadm enable_db SALES_DB 


From the OS command line: 
CALL QDBXM/QZXMADM PARM(enable_db SALES_DB) 


From the iSeries Navigator: 
CALL MYSCHEMA.QZXMADM('enable_db', 'SALES_DB'); 


Related reference: 


* |“Purpose of the administration command” on page 149 


Related samples: 
* “dxx_xml -- s-getstart_prep_NT-cmd.htm” 
* “dxx_xml -- s-getstart_prep-cmd.htm” 


disable_db option 


Purpose: 
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Disables XML Extender features for a database; this action is called “disabling 
a database.” When the database is disabled, it can no longer be used by the 
XML Extender. When the XML Extender disables the database, it drops the 
following objects: 


* The XML Extender user-defined types (UDTs). 
* The XML Extender user-defined functions (UDFs). 


¢ The XML Extender DTD reference table, DTD_REF, which stores DTDs and 
information about each DTD. 


* The XML Extender usage table, XML_USAGE, which stores common 
information for each column that is enabled for XML and for each 
collection. 


Important: You must disable all XML columns before attempting to disable a 
database. The XML Extender cannot disable a database that contains columns 
or collections that are enabled for XML. You must also drop all tables that 
have columns defined with XML Extender user-defined types, such as 
XMLCLOB. 


Syntax: 
>>—dxxadm—disable_db—db_name >< 
-]1—login -p—pas sword: 

Parameters: 

Table 20. disable_db parameters 

Parameter Description 

db_name The name of the RDB database in which 
the XML data resides 

-1 login The user ID used to connect to the 
database. If not specified, the current user 
ID is used. 

-p password The password used to connect to the 


database. If not specified, the current 
password is used. 


Examples: 
The following example disables the database SALES_DB. 


From the Qshell: 
dxxadm disable_db SALES_DB 


From the OS command line: 
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CALL QDBXM/QZXMADM PARM(disable_db SALES_DB) 


From the iSeries Navigator: 
CALL MYSCHEMA.QZXMADM('disable_db', 'SALES_DB'); 


Related concepts: 


* |Chapter 11, “XML Extenders administration support tables” on page 251 


Related reference: 


* |“XML Extender administration stored procedures” on page 224, 
* |“How to read syntax diagrams” on page xi 


enable_column option 
Purpose: 


Connects to a database and enables an XML column so that it can contain the 
XML Extender UDTs. When enabling a column, the XML Extender completes 
the following tasks: 

* Determines whether the XML table has a primary key; if not, the XML 
Extender alters the XML table and adds a column called DXXROOT_ID. 

* Creates side tables that are specified in the DAD file with a column 
containing a unique identifier for each row in the XML table. This column 
is either the root ID that the user specified or the DXXROOT_ID that was 
named by the XML Extender. 

* Optionally creates a default view for the XML table and its side tables, 
optionally using a name that you specify. 


Syntax: 


>>—dxxadm—enable_column—db_name—tab_name—column_name—DAD_file 


>- 


'_-v—de fault_view | -r—root_id- | -1—login | -p—pas sword: | 


Parameters: 


Table 21. enable_column parameters 


>< 


Parameter Description 

db_name The name of the RDB database in which 
the XML data resides. 

tab_name The name of the table in which the XML 


column resides. 


column_name The name of the XML column. 
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Table 21. enable_column parameters (continued) 


Parameter Description 


DAD_file The name of the DAD file that maps the 
XML document to the XML column and 
side tables. 


-v default_view The name of the default view that joins 
the XML column and side tables. 


-r root_id The name of the primary key in the XML 
column table that is to be used as the 
root_id for side tables. The root_id is 


optional. 

-] login The user ID, used to connect to the 
database. If not specified, the current user 
ID is used. 

-p password The password used to connect to the 


database. If not specified, the current 
password is used. 


Examples: 
The following example enables an XML column. 


From the Qshell: 


dxxadm enable_column SALES_DB MYSCHEMA.SALES_TAB ORDER getstart.dad 
-v sales_order_view -r INVOICE_NUMBER 


From the OS command line: 


CALL QDBXM/QZXMADM PARM(enable_column SALES _DB 'MYSCHEMA.SALES_TAB' 
ORDER 'getstart.dad' '-v' sales_order_view '-r' INVOICE_NUMBER) 


From the iSeries Navigator: 


CALL MYSCHEMA.QZXMADM('enable_column', 'SALES_DB', 'MYSCHEMA.SALES TAB', 
‘ORDER', 'getstart.dad', '-v sales_order_view', '-r INVOICE_NUMBER'); 


Related samples: 
* “dxx_xml -- s-getstart_enableCol_NT-cmd.htm” 
* “dxx_xml -- s-getstart_enableCol-cmd.htm” 


disable_column option 


Purpose: 
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Connects to a database and disables the XML-enabled column. When the 
column is disabled, it can no longer contain XML data types. When an 
XML-enabled column is disabled, the following actions are performed: 


* The XML column usage entry is deleted from the XML_USAGE table. 
* The USAGE_COUNT is decremented in the DTD_REF table. 

* All triggers that are associated with this column are dropped. 

* All side tables that are associated with this column are dropped. 


Important: You must disable an XML column before dropping an XML table. 
If an XML table is dropped but its XML column is not disabled, the XML 
Extender keeps both the side tables that it created and the XML column entry 
in the XML_USAGE table. 


Syntax: 


>>—dxxadm—disable_column—db_name—tab_name—column_name L 7 > 
-1—login 


>- >< 


eer a 


Parameters: 


Table 22. disable_column parameters 


Parameter Description 

db_name The name of the RDB database in which 
the data resides. 

tab_name The name of the table in which the XML 
column resides. 

column_name The name of the XML column. 

-] login The user ID used to connect to the 
database. If not specified, the current user 
ID is used. 

-p password The password used to connect to the 


database. If not specified, the current 
password is used. 


Examples: 
The following example disables an XML-enabled column. 


From the Qshell: 
dxxadm disable_column SALES_DB MYSCHEMA.SALES_TAB ORDER 
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From the OS command line: 
CALL QDBXM/QZXMADM PARM(disable_column SALES_DB 'MYSCHEMA.SALES_TAB' ORDER) 


From the iSeries Navigator: 


CALL MYSCHEMA.QZXMADM('disable_column', 'SALES_DB', 
'MYSCHEMA.SALES_TAB', 'ORDER'); 


Related reference: 


* |“enable_collection option” on page 155 


Related samples: 
* “dxx_xml -- s-getstart_clean_NT-cmd.htm” 
* “dxx_xml -- s-getstart_clean-cmd.htm” 


enable_collection option 
Purpose: 


Connects to a database and enables an XML collection according to the 
specified DAD. When enabling a collection, the XML Extender does the 
following tasks: 

* Creates an XML collection usage entry in the XML_USAGE table. 


* For RDB_node mapping, creates collection tables specified in the DAD if 
the tables do not exist in the database. 


Syntax: 


>>—dxxadm—enable_collection—db_name—collection_name—DAD_file L 7 > 
-1—login 


>. >< 


Lege snesawendl 


Parameters: 


Table 23. enable_collection parameters 


Parameter Description 

db_name The name of the RDB database in which 
the data resides. 

collection_name The name of the XML collection. 

DAD_file The name of the DAD file that maps the 


XML document to the relational tables in 
the collection. 
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Table 23. enable_collection parameters (continued) 


Parameter Description 


-] login The user ID used to connect to the 
database. If not specified, the current user 
ID is used. 


-p password The password used to connect to the 
database. If not specified, the current 
password is used. 


Examples: 
The following example enables an XML collection. 


From the Qshell: 


dxxadm enable collection SALES DB sales_ord 
getstart_xcollection.dad 


From the OS command line: 


CALL QDBXM/QZXMADM PARM(enable_collection SALES _DB sales_ord 
'getstart_collection.dad') 


From the iSeries Navigator: 
CALL MYSCHEMA.QZXMADM('enable_collection', 'SALES DB', 'sales ord’, 
'getstart_collection.dad'); 


disable_collection option 
Purpose: 


Connects to a database and disables an XML-enabled collection. The collection 
name can no longer be used in the composition (dxxRetrieveXML) and 
decomposition (dxxInsertXML) stored procedures. When an XML collection is 
disabled, the associated collection entry is deleted from the XML_USAGE 
table. Disabling the collection does not drop the collection tables that are 
created during when you use enable_collection option. 


Syntax: 


>>—dxxadm—disable_collection—db_name—collection_name > 


eres 


>< 


ea nent ceeuaigl 


Parameters: 
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Table 24. disable_collection parameters 


Parameter 


Description 


db_name 


The name of the RDB database in which 
the data resides. 


collection_name 


The name of the XML collection. 


-] login The user ID used to connect to the 
database. If not specified, the current user 
ID is used. 

-p password The password used to connect to the 
database. If not specified, the current 
password is used. 

Examples: 


The following example disables an XML collection. 


From the Qshell: 


dxxadm disable_collection SALES _DB sales_ord 


From the OS command line: 


CALL QDBXM/QZXMADM PARM(disable_collection SALES DB sales ord) 


From the iSeries Navigator: 


CALL MYSCHEMA.QZXMADM('disable_collection', 'SALES_DB', 'sales_ord'); 


Chapter 6. The dxxadm administration command 157 


158 Administration and Programming for iSeries 


Part 4. Reference 


This part provides syntax information for the XML Extender administration 
command, user-defined data types (UDTs), user-defined functions (UDFs), and 
stored procedures. Message text is also provided for problem determination 
activities. 
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Chapter 7. XML Extender user-defined types 


The data types are used to define the column in the application table that will 
be used to store the XML document. You can also store XML documents as 
files on the file system, by specifying a file name. 


All the XML Extender’s user-defined types have the qualifier DB2XML, which 
is the schema name of the DB2 XML Extender user-defined types. For example: 


db2xm1 .XMLVarchar 


All the UDTs have the schema name DB2XML. The XML Extender creates 
UDTs for storing and retrieving XML documents. |Table 25] describes the UDTs. 


Table 25. The XML Extender UDTs 


User-defined type column | Source data type Usage description 

XMLVARCHAR VARCHAR (varchar_len) Stores an entire XML 
document as VARCHAR 
inside DB2. 

XMLCLOB CLOB(clob_len) Stores an entire XML 


document as character large 
object (CLOB) inside DB2. 


XMLFILE VARCHAR(512) Specifies the file name of 
the local file server. If 
XMLFILE is specified for 
the XML column, then the 
XML Extender stores the 
XML document in an 
external server file. The 
Text Extender cannot be 
enabled with XMLFILE. It 
is your responsibility to 
ensure integrity between 
the file content and DB2, as 
well as the side table 
created for indexing. 


Where varchar_len and clob_len are specific to the operating system. 

For XML Extender on iSeries, varchar_len = 3K and clob_len = 10M. 

These UDTs are used only to specify the types of application columns; they do 
not apply to the side tables that the XML Extender creates. 


© Copyright IBM Corp. 1999, 2003 161 


Related concepts: 


“Mapping schemes for XML collections” on page 125 


Related samples: 
* “dxx_xml -- s-getstart_alterTabCol_NT-cmd.htm” 
* “dxx_xml -- s-getstart_alterTabCol-cmd.htm” 


162 Administration and Programming for iSeries 


Chapter 8. XML Extender user-defined functions 


A user-defined function (UDF) is a function that is defined to the database 
management system and can be referenced in SQL statements. This chapter 
describes user-defined functions that are used by DB2 XML Extender. 


XML Extender user-defined functions 


The XML Extender provides functions for storing, retrieving, searching, and 
updating XML documents, and for extracting XML elements or attributes. You 
use XML user-defined functions (UDFs) for XML columns, but not for XML 
collections. 


All the UDFs have the schema name DB2XML. 


The types of XML Extender functions are described in the following list: 


storage functions 
Storage functions insert intact XML documents in XML-enabled 
columns as XML data types 


retrieval functions 
Retrieval functions retrieve XML documents from XML columns in a 
DB2® database. 


extracting functions 
Extracting functions extract and convert the element content or 
attribute value from an XML document to the data type that is 
specified by the function name. The XML Extender provides a set of 
extracting functions for various SQL data types. 


update function 
The Update function modifies an entire XML document or specified 
element content or attribute values and returns a copy of an XML 
document with an updated value, which is specified by the location 
path. 


generate_unique function 
The generate_unique function returns a unique key. 


Validation functions 
Validation functions validate XML documents against either an XML 
schema or a DTD. 
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The XML user-defined functions allow you to perform searches on general 
SQL data types. Additionally, you can use the DB2 UDB Text Extender with 
the XML Extender to perform structural and full text searches on text in XML 
documents. This search capability can be used, for example, to improve the 
usability of a Web site that publishes large amounts of readable text, such as 
newspaper articles or Electronic Data Interchange (EDI) applications, which 
have frequently searchable elements or attributes. 


When using parameter markers in UDFs, a Java’” database (JDBC) restriction 
requires that the parameter marker for the UDF must be cast to the data type 
of the column into which the returned data will be inserted. 


Storage functions 
Storage functions 
Use storage functions to insert XML documents into a DB2 database. You can 
use the default casting functions of a UDT directly in INSERT or SELECT 
statements. Additionally, the XML Extender provides UDFs to take XML 


documents from sources other than the UDT base data type and convert them 
to the specified UDT. 


XMLCLOBFromile() function 


Purpose: 


Reads an XML document from a server file and returns the document as an 
XMLCLOB type. 


Syntax: 


>>—XMLCLOBFromF i 1 e—(—fileName—) >< 


Parameters: 


Table 26. XMLCLOBFromFile parameter 


Parameter Data type Description 

fileName VARCHAR(512) The fully qualified server 
file name. 

Results: 


XMLCLOB as LOCATOR 


Examples: 
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The following example reads an XML document from a server file and inserts 
it into an XML column as an XMLCLOB type. 


EXEC SQL INSERT INTO sales_tab(ID, NAME, ORDER) 
VALUES ('1234', ‘Sriram Srinivasan’, 
XMLCLOBFromFile(' 
dxxsamples/xml/getstart.xml ')) 
The column ORDER in the SALES_TAB table is defined as an XMLCLOB 
type. 
Related samples: 
* “dxx_xml -- s-getstart_insertDTD_NT-cmd.htm” 
* “dxx_xml -- s-getstart_insertDTD-cmd.htm” 


XMLFileFromCLOB() function 
Purpose: 


Reads an XML document as CLOB locator, writes it to an external server file, 
and returns the file name and path as an XMLFILE type. 


Syntax: 


>>—XMLFi 1 eFromCLOB—(—buf fer—,—fi leName—) >< 


Parameters: 


Table 27. XMLFileFromCLOB() parameters 


Parameters Data type Description 

buffer CLOB as LOCATOR The buffer containing the 
XML document. 

fileName VARCHAR(512) The fully qualified server 
file name. 

Results: 

XMLFILE 

Examples: 


The following example reads an XML document as CLOB locator (a host 
variable with a value that represents a single LOB value in the database 
server), writes it to an external server file, and inserts the file name and path 
as an XMLFILE type in an XML column. 
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EXEC SQL BEGIN DECLARE SECTION; 
SQL TYPE IS CLOB_LOCATOR xm1_buff; 
EXEC SQL END DECLARE SECTION; 


EXEC SQL INSERT INTO sales_tab(ID, NAME, ORDER) 


VALUES ('1234', ‘Sriram Srinivasan’, 
XMLFileFromCLOB(:xml_buf, 'dxxsamples/xml/getstart.xml ')) 


The column ORDER in the SALES_TAB table is defined as an XMLFILE type. 
If you have an XML document in your buffer, you can store it in a server file. 


XMLFileFromVarchar() function 
Purpose: 


Reads an XML document from memory as VARCHAR, writes it to an external 
server file, and returns the file name and path as an XMLFILE type. 


Syntax: 


>>—XMLFi]leFromVarchar—(—buf fer—,—fileName—) >< 


Parameters: 


Table 28. XMLFileFromVarchar parameters 


Parameter Data type Description 

buffer VARCHAR(K) The memory buffer. 

fileName VARCHAR(512) The fully qualified server 
file name. 

Results: 

XMLFILE 

Examples: 


The following examples reads an XML document from memory as 
VARCHAR, writes it to an external server file, and inserts the file name and 
path as an XMLFILE type in an XML column. 

EXEC SQL BEGIN DECLARE SECTION; 


struct { short len; char data[3000]; } xml_buff; 
EXEC SQL END DECLARE SECTION; 


EXEC SQL INSERT INTO sales_tab(ID, NAME, ORDER) 


VALUES('1234', ‘Sriram Srinivasan’, 
XMLFileFromVarchar(:xml_buf, 'dxxsample/xml/getstart.xml')) 
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The column ORDER in the SALES_TAB table is defined as an XMLFILE type. 
XMLVarcharFromFile() function 


Purpose: 


Reads an XML document from a server file and returns the document as an 
XMLVARCHAR type. 


Syntax: 


>>—XMLVarcharFromFi le—(—fileName—) >< 


Parameters: 


Table 29. XMLVarcharFromFile parameter 


Parameter Data type Description 

fileName VARCHAR(512) The fully qualified server 
file name. 

Results: 

XMLVARCHAR 

Examples: 


The following example reads an XML document from a server file and inserts 
it into an XML column as an XMLVARCHAKR type. 


EXEC SQL INSERT INTO sales_tab(ID, NAME, ORDER) 
VALUES('1234', ‘Sriram Srinivasan’, 
XMLVarcharFromFile('dxxsample/xml/getstart.xml ')) 


In this example, a record is inserted into the SALES_TAB table. The function 
XMLVarcharFromFile() imports the XML document from a file into DB2 and 
stores it as a XMLVARCHAR. 


Related samples: 
* “dxx_xml -- s-getstart_insertXML_NT-cmd.htm” 
* “dxx_xml -- s-getstart_insertXML-cmd.htm” 
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Retrieval functions 


About retrieval functions 


The XML Extender provides an overloaded function Content(), which is used 
for retrieval. This overloaded function refers to a set of retrieval functions that 
have the same name, but behave differently based on where the data is being 
retrieved. You can also use the default casting functions to convert an XML 
UDT to the base data type. 


The Content() functions provide the following types of retrieval: 


* Retrieval from external storage at the server to a host variable at the 
client. 


You can use Content() to retrieve an XML document to a memory buffer 
when it is stored as an external server file. You can use Content(): retrieve 
from XMLFILE to a CLOB for this purpose. 


* Retrieval from internal storage to an external server file 


You can also use Content() to retrieve an XML document that is stored 
inside DB2 and store it to a server file on the DB2 server’s file system. The 
following Content() functions are used to store information on external 
server files: 


— Content(): retrieve from XMLVARCHAR to an external server file 
— Content(): retrieval from XMLCLOB to an external server file 


The examples in the following section assume you are using the DB2 


command shell, in which you do not need to type “DB2” at the beginning of 
each command. 


Conitent(): retrieve from XMLFILE to a CLOB 
Purpose: 
Retrieves data from a server file and stores it in a CLOB LOCATOR. 


Syntax: 


»>>—Content—(—xmlobj—) >< 


Parameters: 


Table 30. XMLFILE to a CLOB parameter 


Parameter Data type Description 
xmlobj XMLFILE The XML document. 
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Results: 

CLOB (clob_len) as LOCATOR 
clob_len for DB2 is 2G. 
Examples: 


The following example retrieves data from a server file and stores it in a 
CLOB locator. The examples assume that you are using the DB2 command 
shell, in which you do not need to type "DB2” at the beginning of each 
command. 

EXEC SQL BEGIN DECLARE SECTION; 


SQL TYPE IS CLOB LOCATOR xm1_buff; 
EXEC SQL END DECLARE SECTION; 


EXEC SQL CONNECT TO SALES_DB 
EXEC SQL DECLARE cl CURSOR FOR 


SELECT Content(order) from sales_tab 
WHERE sales_person = ‘Sriram Srinivasan’ 


EXEC SQL OPEN cl; 


do { 
EXEC SQL FETCH cl INTO :xml_buff; 
if (SQLCODE != 0) { 
break; 
} 
else { 
/* do with the XML doc in buffer */ 
} 
} 


EXEC SQL CLOSE cl; 


EXEC SQL CONNECT RESET; 


The column ORDER in the SALES_TAB table is of an XMLFILE type, so the 
Content() UDF retrieves data from a server file and stores it in a CLOB 
locator. 


Content(): retrieve from XMLVARCHAR to an external server file 


Purpose: 
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Retrieves the XML content that is stored as an XMLVARCHAR type and stores 
it in an external server file. 


Syntax: 


»>—Content—(—xmlobj—,—filename—) >< 
Important: If a file with the specified name already exists, the content 
function overrides its content. 


Parameters: 


Table 31. XMLVarchar to external server file parameters 


Parameter Data type Description 

xmlobj XMLVARCHAR The XML document. 

filename VARCHAR(512) The fully qualified server 
file name. 

Results: 

VARCHAR(512) 

Examples: 


The following example retrieves the XML content that is stored as 
XMLVARCHAR type and stores it in an external server file. The examples 
assume that you are using the DB2 command shell, in which you do not need 
to type "DB2" at the beginning of each command. 


CREATE table appl (id int NOT NULL, order DB2XML.XMLVarchar) ; 
INSERT into appl values (1, '<?xml version="1.0"2?> 
<!DOCTYPE SYSTEM 
"dxxsample/dtd/getstart.dtd"-> 
<Order key="1"> 
<Customer> 
<Name>American Motors</Name> 
<Emai1>parts@am.com</Emai1> 
</Customer> 
<Part color="black"> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850. 16</ExtendedPrice> 
<Tax>6.000000e-02</Tax> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>AIR </ShipMode> 
</Shipment> 
<Shi pment> 
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<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>BOAT </ShipMode> 
</Shipment> 
</Part> 
</Order>'); 


SELECT DB2XML.Content(order, ' 


dxxsamples/dad/getstart_column.dad') 
from appl where ID=1; 


Related tasks: 


* ‘Retrieving XML data” on page 98 


Related reference: 


* |About retrieval functions” on page 168 


Content(): retrieval from XMLCLOB to an external server file 
Purpose: 


Retrieves the XML content that is stored as an XMLCLOB type and stores it in 
an external server file. 


Syntax: 


>>—Content— (—xmlobj—,—filename—) >< 
Important: If a file with the specified name already exists, the content 
function overrides its content. 


Parameters: 


Table 32. XMLCLOB to external server file parameters 


Parameter Data type Description 

xmlobj XMLCLOB as LOCATOR The XML document. 

filename VARCHAR(512) The fully qualified server 
file name. 

Results: 

VARCHAR(512) 

Examples: 
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The following example retrieves the XML content that is stored as an 
XMLCLOB type and stores it in an external server file. The examples assume 
that you are using the DB2 command shell, in which you do not need to type 
"DB2” at the beginning of each command. 


CREATE table appl (id int NOT NULL, order DB2XML.XMLCLOB ); 


INSERT into appl values (1, '<?xml version="1.0"2?> 
<!DOCTYPE SYSTEM 
"dxxsamples/dtd/getstart.dtd"-> 
<Order key="1"> 
<Customer> 
<Name>American Motors</Name> 
<Emai1>parts@am. com</Emai1> 


</Customer> 
<Part color="black"> 
<key>68</key> 


<Quantity>36</Quantity> 
<ExtendedPrice>34850.16</ExtendedPrice> 
<Tax>6.000000e-02</Tax> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>AIR </ShipMode> 
</Shipment> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>BOAT </ShipMode> 
</Shipment> 
</Part> 
</Order>'); 


SELECT DB2XML.Content(order, 'dxxsamples/xml/getstart.xml ') 
from appl where ID=1; 


Related samples: 
* “dxx_xml -- s-getstart_exportXML_NT-cmd.htm” 
* “dxx_xml -- s-getstart_exportXML-cmd.htm” 


Extraction functions 


About extracting functions 


The extracting functions extract the element content or attribute value from an 
XML document and return the requested SQL data types. The XML Extender 
provides a set of extracting functions for various SQL data types. The 
extracting functions take two input parameters. The first parameter is the 
XML Extender UDT, which can be one of the XML UDTs. The second 
parameter is the location path that specifies the XML element or attribute. 
Each extracting function returns the value that is specified by the location 
path. 
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The examples assume you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 


extractinteger() and extractintegers() 
Purpose: 


Extracts the element content or attribute value from an XML document and 
returns the data as INTEGER type. 


Syntax: 


>>—extract Integer—(—xmlobj—,—path—) >< 


Table function: 


>>—extract Integers—(—xmlobj—,—path—) >< 


Parameters: 


Table 33. extractinteger function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
INTEGER 
Examples: 


In the following example, one value is returned when the attribute value of 
key = "1". The value is extracted as an INTEGER. The examples assume that 
you are using the DB2 command shell, in which you do not need to type 
“DB2” at the beginning of each command. 
CREATE TABLE t1(key INT); 
INSERT INTO t1 values ( 

DB2XML. extract Integer (DB2XML.XMLFile(' 

dxxsamples/xml/getstart.xml'), 

'/Order/Part [@color="black "]/key')); 
SELECT * from tl; 


Table function example: 
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In the following example, each order key for the sales orders is extracted as 
INTEGER. The examples assume that you are using the DB2 command shell, 
in which you do not need to type “DB2” at the beginning of each command. 
SELECT * 
FROM TABLE ( 

DB2XML. extract Integers (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/0rder/Part/key')) AS X; 


Related concepts: 


“User-defined types and user-defined function names for XML Extender” 


“XML Extender user-defined functions” on page 163 


Related reference: 


* |About extracting functions” on page 172 


extractSmallint() and extractSmallints() 
Purpose: 


Extracts the element content or attribute value from an XML document and 
returns the data as SMALLINT type. 


Syntax: 


>>—extractSmal 1 int—(—xmlobj—,—path—) 


Table function: 


>>—extractSmal] ints—(—xmlobj—,—path—) 


>< 


>< 


Parameters: 


Table 34. extractSmallint function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
SMALLINT 


Examples: 
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In the following example, the value of key in all sales orders is extracted as 
SMALLINT. The examples assume that you are using the DB2 command shell, 
in which you do not need to type “DB2” at the beginning of each command. 


CREATE TABLE t1(key INT); 

INSERT INTO tl values ( 
DB2XML.extractSmal]int (b2xm].xmlfile('dxxsamples/xml/getstart.xml'), 
'/Order/Part[@color="black "]/key')); 

SELECT * from tl; 


Table function example: 


In the following example, the value of key in all sales orders is extracted as 
SMALLINT. The examples assume that you are using the DB2 command shell, 
in which you do not need to type “DB2” at the beginning of each command. 


SELECT * 
FROM TABLE ( 
DB2XML.extractSmallints (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/key')) AS X; 


Related concepts: 
* Using indexes for XML column data” on page 94 


¢ User-defined types and user-defined function names for XML Extender” 


* (“XML Extender user-defined functions” on page 163 


Related reference: 


* ‘About extracting functions” on page 172 
* “XML Extenders stored procedure return codes” on page 258 


extractDouble() and extractDoubles() 
Purpose: 


Extracts the element content or attribute value from an XML document and 
returns the data as DOUBLE type. 


Syntax: 


»>>—extractDoubl e—(—xmlobj—,—path—) ——_____________________—_»« 


Table function: 


>>—extractDoubles—(—xmlobj—,—path—) >< 


Parameters: 
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Table 35. extractDouble function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
DOUBLE 
Examples: 


The following example automatically converts the price in an order from a 
DOUBLE type to a DECIMAL. The examples assume that you are using the 
DB2 command shell, in which you do not need to type “DB2” at the 
beginning of each command. 

CREATE TABLE t1(price DECIMAL(9,2)); 

INSERT INTO t1 values ( 
DB2XML.extractDouble(DB2XML.xmlfile('dxxsamples/xml/getstart.xml'), 
'/Order/Part[@color="black "]/ExtendedPrice')); 

SELECT * from tl; 


Table function example: 


In the following example, the value of ExtendedPrice in each part of the sales 
order is extracted as DOUBLE. The examples assume that you are using the 
DB2 command shell, in which you do not need to type DB2 at the beginning 
of each command. 


SELECT CAST(RETURNEDDOUBLE AS DOUBLE) 
FROM TABLE( 
DB2XML.extractDoubles (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/ExtendedPrice')) AS X; 


Related concepts: 


* {User-defined types and user-defined function names for XML Extender” 


Related reference: 


* “About extracting functions” on page 172 


extractReal() and extractReals() 


Purpose: 
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Extracts the element content or attribute value from an XML document and 
returns the data as REAL type. 


Syntax: 


>>—extractReal—(—xmlobj—,—path—) >< 


Table function: 


>>—extractReals—(—xmlobj—,—path—) >< 


Parameters: 


Table 36. extractReal function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
REAL 
Examples: 


In the following example, the value of ExtendedPrice is extracted as a REAL. 
The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. 
CREATE TABLE tl(price DECIMAL(9,2)); 
INSERT INTO t1 values ( 
DB2XML.extractReal (DB2XML. xml file('dxxsamples/xml/getstart.xml'), 
'/Order/Part [@color="black"]/ExtendedPrice')); 
SELECT * from tl; 


Table function example: 


In the following example, the value of ExtendedPrice is extracted as a REAL. 
The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. 
SELECT CAST(RETURNEDREAL AS REAL) 
FROM TABLE ( 
DB2XML.extractReals (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/ExtendedPrice')) AS X; 


Related concepts: 
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* ‘User-defined types and user-defined function names for XML Extender” 


ion page 144 


* “XML Extender user-defined functions” on page 163 


Related reference: 


* ‘About extracting functions” on page 172 
* |XML Extenders UDF return codes” on page 257 


extractChar() and extractChars() 


Purpose: 


Extracts the element content or attribute value from an XML document and 


returns the data as CHAR type. 


Syntax: 


>< 


>>—extractChar—(—xmlobj—,—path—) 


Table function: 


>< 


>>—extractChars—(—xmlobj—,—path—) 


Parameters: 


Table 37. extractChar function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
CHAR 


Examples: 


In the following example, the value of Name is extracted as CHAR. The 
examples assume that you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 
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CREATE TABLE t1(name char(30)); 

INSERT INTO tl values ( 
DB2XML.extractChar (DB2XML. xml file('dxxsamples/xml/getstart.xml'), 
'/Order/Customer/Name')) ; 

SELECT * from tl; 


Table function example: 


In the following example, the value of Color is extracted as CHAR. The 
examples assume that you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 


SELECT * 
FROM TABLE ( 
DB2XML.extractChars (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/@color')) AS X; 


Related reference: 


* |‘About extracting functions” on page 172 
* “How to read syntax diagrams” on page xi 


extractVarchar() and extractVarchars() 
Purpose: 


Extracts the element content or attribute value from an XML document and 
returns the data as VARCHAR type. 


Syntax: 


>>—extractVarchar—(—xmlobj—,—path—) >< 


Table function: 


>>—extractVarchars—(—xmlobj—,—path—) >< 


Parameters: 


Table 38. extractVarchar function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
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VARCHAR(4K) 
Examples: 


In a database with more than 1000 XML documents that are stored in the 
column ORDER in the SALES_TAB table, you might want to find all the 
customers who have ordered items that have an ExtendedPrice greater than 
2500.00. The following SQL statement uses the extracting UDF in the SELECT 
clause: 


SELECT extractVarchar(Order, '/Order/Customer/Name') from sales_order_view 
WHERE price > 2500.00 


The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. The UDF 
extractVarchar() takes the column ORDER as the input and the location path 
/Order/Customer/Name as the select identifier. The UDF returns the names of 
the customers. With the WHERE clause, the extracting function evaluates only 
those orders with an ExtendedPrice greater than 2500.00. 


Table function example: 


In a database with more than 1000 XML documents that are stored in the 
column ORDER in the SALES_TAB table, you might want to find all the 
customers who have ordered items that have an ExtendedPrice greater than 
2500.00. The following SQL statement uses the extracting UDF in the SELECT 
clause: 


SELECT extractVarchar(Order, '/Order/Customer/Name') from sales_order_view 
WHERE price > 2500.00 


The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. The UDF 
extractVarchar() takes the column ORDER as the input and the location path 
/Order/Customer/Name as the select identifier. The UDF returns the names of 
the customers. With the WHERE clause, the extracting function evaluates only 
those orders with an ExtendedPrice greater than 2500.00. 


In the following example, the value of Name is extracted as VARCHAR. The 
examples assume that you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 
CREATE TABLE t1(name varchar(30)); 
INSERT INTO t1 values ( 
DB2XML.extractVarchar (DB2XML. xml file('dxxsamples/xml/getstart.xml'), 
'/Order/Customer/Name')); 
SELECT * from tl; 


Table function example: 
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In the following example, the value of Color is extracted as VARCHAR. The 
examples assume that you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 
SELECT* 

FROM TABLE ( 


DB2XML.extractVarchars (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/@color')) AS X; 


Related concepts: 
User-defined types and user-defined function names for XML Extender” 


XML Extender user-defined functions” on page 163 


Related reference: 


* {‘About extracting functions” on page 172 
¢ XML Extenders UDF return codes” on page 257 


extractCLOB() and extractCLOBs() 


Purpose: 


Extracts a fragment of XML documents, with element and attribute markup 
and content of elements and attributes, including sub-elements. This function 
differs from the other extract functions, which return only the content of 
elements and attributes. The extractClob(s) functions are used to extract 
document fragments, whereas extractVarchar(s) and extractChar(s) are used to 
extract simple values. 


Syntax: 


>>—extractCLOB—(—xmlobj—,—path—) >< 


Table function: 


>>—extractCLOBs—(—xmlobj—,—path—) —— >< 


Parameters: 


Table 39. extractCLOB function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 
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Returned Type: 
CLOB(10K) 
Examples: 


In this example, all name element content and tags are extracted from a 
purchase order. The examples assume that you are using the DB2 command 
shell, in which you do not need to type “DB2” at the beginning of each 
command. 
CREATE TABLE t1(name DB2XML.xm1clob); 
INSERT INTO t1 values ( 
DB2XML.extractClob(DB2XML. xml file('dxxsamples/xml/getstart.xml'), 
'/Order/Customer/Name')); 
SELECT * from tl; 


Table function example: 


In this example, all of the color attributes are extracted from a purchase order. 
The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. 


SELECT * 
FROM TABLE( 
DB2XML.extractCLOBs (DB2XML.XMLFile('dxxsamples/xml/getstart.xml'), 
'/Order/Part/@color')) AS X; 


Related concepts: 
* “XML Extender user-defined functions” on page 163 


Related reference: 


* |“About extracting functions” on page 172 


extractDate() and extractDates() 
Purpose: 
Extracts the element content or attribute value from an XML document and 
returns the data as DATE type. The date must be in the format: 
YYYY-MM-DD. 


Syntax: 


>>—extractDate—(—xmlobj—,—path—) >< 


Table function: 
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>>—extractDates—(—xmlobj—,—path—) >< 


Parameters: 


Table 40. extractDate function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
DATE 
Examples: 


In the following example, the value of ShipDate is extracted as DATE. The 
examples assume that you are using the DB2 command shell, in which you do 
not need to type “DB2” at the beginning of each command. 


CREATE TABLE tl(shipdate DATE); 

INSERT INTO tl values ( 
DB2XML.extractDate(DB2XML.xmlfile(''), 
'/Order/Part[@color="red "]/Shipment/ShipDate')); 

SELECT * from tl; 


Table function example: 


In the following example, the value of ShipDate is extracted as DATE. 


SELECT * 
FROM TABLE( 
DB2XML.extractDates (DB2XML.XMLFile(''), 
'/Order/Part[@color="black "]/Shipment/ShipDate')) AS X; 


Related concepts: 


* (“XML Extender user-defined functions” on page 163 


Related reference: 


* (“About extracting functions” on page 172 
* (XML Extenders UDF return codes” on page 257 


extractTime() and extractTimes() 


Purpose: 


Chapter 8. XML Extender user-defined functions 183 


Extracts the element content or attribute value from an XML document and 
returns the data as TIME type. 


Syntax: 


>>—extractTime—(—xmlobj—,—path—) 


Table function: 


>>—extractTimes—(—xmlobj—,—path—) 


Parameters: 


Table 41. extractTime function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
TIME 


Examples: 


CREATE TABLE t1(testtime TIME); 
INSERT INTO t1 values ( 
DB2XML.extractTime (DB2XML.XMLCLOB( 
‘<stuff><data>11.12.13</data></stuff>'), '//data')); 
SELECT * from tl; 


Table function example: 


select * 
from table( 
DB2XML.extractTimes (DB2XML.XMLCLOB( 
'<stuf f><data>01.02.03</data><data>11.12.13</data></stuff>'), 
'//data')) as x; 


The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. 


Related concepts: 


* |“User-defined types and user-defined function names for XML Extender” 


* “XML Extender user-defined functions” on page 163 
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Related reference: 


* |About extracting functions” on page 172 


extractTimestamp() and extractTimestamps() 
Purpose: 


Extracts the element content or attribute value from an XML document and 
returns the data as TIMESTAMP type. 


Syntax: 


>>—extractTimestamp—(—xmlobj—,—path—) >< 


Table function: 


>>—extractTimestamps—(—xmlobj—,—path—) >< 


Parameters: 


Table 42. extractTimestamp function parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, The column name. 
XMLFILE, or 
XMLCLOB 
path VARCHAR The location path of the 
element or attribute. 


Returned Type: 
TIMESTAMP 


Examples: 


CREATE TABLE t1(testtimestamp TIMESTAMP); 
INSERT INTO t1 values ( 

DB2XML.extractTimestamp (DB2XML.XMLCLOB ( 
'<stuff><data>1998-11-11-11.12.13.888888</data></stuff>'), 
'//data')); 

SELECT * from tl; 


Table function example: 


select * from 

table(DB2XML.extractTimestamps (DB2XML.XMLC1ob( 
'<stuf f><data>1998-11-11-11.12.13.888888 
</data><data>1998-12-22-11.12.13.888888</data></stuff>'), 
'//data')) as x; 
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The examples assume that you are using the DB2 command shell, in which 
you do not need to type “DB2” at the beginning of each command. 


Related concepts: 


“User-defined types and user-defined function names for XML Extender” 


“XML Extender user-defined functions” on page 163 


Related reference: 


* |‘About extracting functions” on page 172 
* |XML Extenders UDF return codes” on page 257 


Update functions 


Update functions 


The Update() function updates a specified element or attribute value in one or 
more XML documents stored in the XML column. You can also use the default 
casting functions to convert an SQL base type to the XML UDT. 


Purpose 
Takes the column name of an XML UDT, a location path, and a string of the 


update value and returns an XML UDT that is the same as the first input 
parameter. With the Update() function, you can specify the element or 
attribute that is to be updated. 


Syntax 


>>—Update—(—xmlobj—,—path—,—value—) ——________________ >< 


Parameters 
Table 43. The UDF Update parameters 


Parameter Data type Description 
xmlobj XMLVARCHAR, XMLCLOB The column name. 
as LOCATOR 
path VARCHAR The location path of the 


element or attribute. 
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Table 43. The UDF Update parameters (continued) 


Parameter Data type Description 


value VARCHAR The update string. 


Restriction: The Update 
function does not have an 
option to disable output 
escaping; the output of an 
extractClob (which is a 
tagged fragment) cannot be 
inserted using this function. 
Use textual values only. 


Restriction: Note that the Update UDF supports location paths that have 
predicates with attributes, but not elements. For example, the following 
predicate is supported: 


'/Order/Part[@color="black "]/ExtendedPrice' 


The following predicate is not supported: 
'/Order/Part/Shipment/[Shipdate < "11/25/00"]' 


Return type 


Data type Return type 
XMLVARCHAR XMLVARCHAR 
XMLCLOB as LOCATOR XMLCLOB 
Example 


The following example updates the purchase order handled by the 
salesperson Sriram Srinivasan. 
UPDATE sales_tab 


set order = db2xml.update(order, '/Order/Customer/Name', 'IBM') 
WHERE sales_person = ‘Sriram Srinivasan’ 


In this example, the content of /Order/Customer/Name is updated to IBM. 


Usage 
When you use the Update function to change a value in one or more XML 


documents, it replaces the XML documents within the XML column. Based on 
output from the XML parser, some parts of the original document are 
preserved, while others are lost or changed. The following sections describe 
how the document is processed and provide examples of how the documents 
look before and after updates. 
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How the Update function processes the XML document: When the Update 

function replaces XML documents, it must reconstruct the document based on 
the XML parser output. [Table 44] describes how the parts of the document are 

handled, with examples. 


Table 44. Update function rules 


Item or node | XML document code example Status after update 

type 

XML <?xml version='1.0! The XML declaration is 

declaration encoding='utf-8' preserved. 
standalone='yes' > 


DOCTYPE The document type 


declaration is preserved: 
Declaration 


<!DOCTYPE books SYSTEM 
"http://dtds.org/books.dtd" > 
<!DOCTYPE books PUBLIC 
"local.books.dtd" "http://dtds.org/books.dtd" > 
<!DOCTYPE books> 
-Any of 
<!DOCTYPE books 
( S ExternalID ) ? 
[ internal-dtd-subset ] > 
-Such as 
<!DOCTYPE books 
[ <!ENTITY mydog "Spot"> ] >? 
[ internal-dtd-subset ] > 


Comments <!-- comment --> Comments are preserved 
outside the root element. 


Comments inside the root 
element are discarded. 


Elements <books> Elements are preserved. 
content 
</books> 
Attributes id='1' date="01/02/1997" Attributes of elements are 
preserved. 


° After update, double 
quotation marks are used 
to delineate values. 


¢ Data within attributes is 
escaped. 


* Entities are replaced. 
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Table 44. Update function rules (continued) 


Item or node | XML document code example Status after update 
type 
Text Nodes This chapter is about Text nodes (element content) 
my dog &mydog;. are preserved. 
* Data within text nodes is 
escaped. 
¢ Entities are replaced. 


Multiple occurrence: When a location path is provided in the Update() UDF, 
the content of every element or attribute with a matching path is updated 
with the supplied value. This means that if a document has multiple 
occurring location paths, the Update function replaces the existing values with 
the value provided in the value parameter. 


You can specify a predicate in the path parameter to provide distinct locations 
paths to prevent unintentional updates. The Update UDF supports location 
paths that have predicates with attributes, but not elements. 


Generate-unique function 


Generate unique function 


Purpose 
The generate unique function returns a character string that is unique 


compared to any other execution of the same function. There are no 
arguments to this function (the empty parentheses must be specified). The 
result of the function is a unique value. The result cannot be null. 


Syntax 


>>—db2xml .generate_unique() >< 


Return value 
VARCHAR(13) 


Example 
The following example uses db2xml.generate_unique() to generate a unique 


key for a column to be indexed. 
<SQL_stmt> 
SELECT o.order_key, customer_name, customer_email, p.part_key, color, 
quantity, price, tax, ship_id, date, mode from order_tab o, part_tab p, 
(select db2xml.generate_unique() 
as ship_id, date, mode, part_key from ship_tab) as s 
WHERE o.order_key = 1 and 
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p.price > 20000 and 
p.order_key = o.order_key and 
s.part_key = p.part_key 
ORDER BY order_key, part_key, ship_id 
</SQL_stmt> 


Validation functions 


DB2 XML Extender offers two user defined functions (UDFs) which validate 
XML documents against either an XML schema or a DTD. 


An element in an XML document is valid according to a given schema if the 
associated element type rules are satisfied. If all elements are valid, the whole 
document is valid. Using a DTD, however, there is no way to require a 
specific root element. The validation functions return 1 if the document is 
valid or they return 0 and write an error message in the trace file if the 
document is invalid. The functions are: 


* db2xml.svalidate: Validates an XML document instance against the 
specified schema. 


* db2xml.dvalidate: Validates an XML document instance against the 
specified DTD. 


SVALIDATE() function 


This function validates an XML document against a specified schema (or the 
one named in the XML document) and returns either 1 if the document is 
valid or 0 if not. This function assumes an XML document and a schema exist 
on the file system or as a CLOB in DB2. 


Before executing the SVALIDATE function, ensure that XML Extender is 
enabled with your database by executing the following command: 


CALL QDBXM/QZXMADM PARM(enable_db mydbname) 


If the XML document fails the validation, an error message is written to the 
XML Extender trace file. Enable the trace before executing the SVALIDATE 


command. See|“Starting the trace” on page 255|for information on enabling 


the trace. 


Syntax 


>>—SVALIDATE—(—xmlobj ) >< 


= eehentdee) 
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Parameters 
Table 45. The SVALIDATE parameters 


Parameter Data type Description 
xmlobj VARCHAR(256) File path of the XML 
document to be verified. 
CLOB(2G) XML column containing the 
document to be verified. 
schemadoc VARCHAR(256) File path of the schema 
document. 
CLOB(2G) XML column containing the 
schema. 
Examples 
Example 1 


select db2xml.svalidate('/dxxsamples/xml/equiplog2001..xm1') from db2xm1.onerow 


Validates equiplog2001.xml against the schema that is specified within the 
document. 


Example 2 
select db2xml.svalidate(doc,schema) from db2xml.onerow 


Validates an XML document using the specified schema, and both the 
document and schema are stored in DB2 tables. 


DVALIDATE() function 


This function validates an XML document against a specified DTD (or the one 
named in the XML document) and returns either 1 if the document is valid or 
0 if not. This function assumes an XML document and a DTD exist on the file 
system or as a CLOB in DB2. 


Before executing the DVALIDATE function, ensure that XML Extender is 
enabled with your database by executing the following command: 


CALL QDBXM/QZXMADM PARM(enable_db mydbname) 


If the XML document fails the validation, an error message is written to the 
XML Extender trace file. Enable the trace before executing the SVALIDATE 


command. See|“Starting the trace” on page 255|for information on enabling 


the trace. 
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Syntax 


>>—DVALIDATE—(—xmlobj ) >< 
are 
Parameters 
Table 46. The DVALIDATE parameters 
Parameter Data type Description 
xmlobj VARCHAR(256) File path of the XML 
document to be verified. 
CLOB(2G) XML column containing the 
document to be verified. 
dtddoc VARCHAR(256) File path of the DTD 
document. 
CLOB(2G) XML column containing the 
DTD. Either from the 
DTD_REF table or from a 
regular table. 
Examples 


Example 1: Validates equiplog2001.xm1 against the DTD that is specified 
within the document. 


select db2xml.dvalidate('/dxxsamples/xm1/equiplog2001.xm1') from db2xm1.onerow 


Example 2: Validates an XML document using the specified DTD, and both 
the document and DTD are in the file system. 


select db2xml.dvalidate('/dxxsamples/xml/equiplog2001.xm1', 
'/dxxsamples/dtd/equip.dtd') from db2xml.onerow 


Example 3: Validates an XML document using the specified DTD, and both 
the document and DTD are stored in DB2 tables. 


select db2xml.dvalidate (doc,dtdid) from equiplogs, db2xml.dtd_ref \ 
where dtdid='equip.dtd' 
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Chapter 9. Document access definition (DAD) files 


Creating a DAD file for XML columns 


This task is part of the larger task of defining and enabling an XML column. 
See the XML Extender Web site at 
www.ibm.com/software/data/db2/extenders/xmlext/downloads.html for the 
most recent information about DAD files. 


To access your XML data and enable columns for XML data in an XML table, 
you need to define a document access definition (DAD) file. This file defines 
the attributes and key elements of your data that need to be searched within 
the column. For XML columns, the DAD file primarily specifies how 
documents stored within it are to be indexed. The DAD file also specifies a 
DTD to use for validating documents inserted into the XML column. DAD 
files are stored as CLOB data type, and their size limit is 100KB. 


Prerequisites: 


Before you create the DAD file, you need to: 


* Decide which elements or attributes you expect to use often in your search. 
The elements or attributes that you specify are extracted into the side tables 
for fast searches by the XML Extender. 


* Define the location path to represent each element or attribute indexed in a 
side table. You must also specify the type of data that you want the element 
or attribute to be converted to. 


Procedure: 


To create a DAD file, complete the following steps: 
1. Create a new document in a text editor and type the following syntax: 


<?XML version="1.0"?> 
<!DOCTYPE DAD SYSTEM <"path/dtd/dad.dtd">. 


where "path/dtd/dad.dtd "is the path and file name of the DTD for the DAD 
file. A DTD is provided in dxx_instal1\samples\db2xml \dtd 


2. Insert DAD tags after the lines from step 1. 


<DAD> 
</DAD> 


This element will contain all the other elements. 
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3. Specify validation for the document and the column: 
* If you want to validate your entire XML document against a DTD 
before it is inserted into the database: 
a. Insert the following tag to validate the document: 
<dtdid>/dtd_name.dtd</dtdid> 


b. Optional: Validate the column by inserting the following tag: 
<val idation>YES</validation> 
* If you don’t want to validate the document, use the following tag: 
<validation>N0</validation> 


4. Enter <Xcolumn> </Xcolumn> tags to specify that you are using XML 
columns as the access and storage method for your XML data. 


5. Create side tables. For each side table that you want to create: 
a. Specify a <table></table> tag. For example: 


<table name="person_names"> 
</table> 

b. Inside the table tags, insert a <column> tag for each column that you 
want the side table to contain. Each column has four attributes: name, 
type, path and, multi_occurrence. 


Example: 


<table name="person_names">> 
<column name ="fname" 
type="varchar (50) " 
path="/person/firstName" 
multi_occurrence="NO0"/> 
<column name ="]name" 
type="varchar (50) " 
path="/person/lastName" 
multi_occurrence="NO0"/> 
</table> 


Where: 


Name 
Specifies the name of the column that is created in the side 
table. 


Type Indicates the SQL data type in the side table for each indexed 
element or attribute 


Path Specifies the location path in the XML document for each 
element or attribute to be indexed 


Multi_occurrence 
Indicates whether the element or attribute referred to by the 
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path attribute can occur more than once in the XML document. 
The possible values for multi_occurrence are YES or NO. If the 
value is NO, then multiple columns can be specified per table. 
If the value is YES, you can specify only one column in the 
side table. 


6. Save your file with a DAD extension. 


Following is an example of a complete DAD file: 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "dxxsamples\dtd\dad.dtd"> 
<DAD> 
<dtid>C:\SG246130\code\person.dtd</dtdid> 
<validation>YES</validation> 
<Xcolumn> 
<table name="person_names"> 
<column name="fname" 
type="varchar(50) " 
path="/person/firstName" 
mul ti_occurrence="NO"/> 
<column name="]name" 
type="varchar(50) " 
path="/person/lastName" 
multi_occurrence="NO"/> 
</table> 
<table name="person_phone_number"> 
<column name="pnumber" 
type="varchar(20) " 
path="/person/phone/number" 
multi_occurrence="YES"/> 
</table> 
<table name="person_phone_number"> 
<column name="pnumber" 
type="varchar (20) " 
path="/person/phone/number" 
multi_occurrence="YES"/> 
</table> 
<table name="pesron_phone_type"> 
<column name="ptype" 
type="varchar (20) " 
path="/person/phone/type" 
multi_occurrence="YES"/> 
</table> 
<Xcolumn> 
</DAD> 


Now that you have created a DAD file, the next step to defining and enabling 
an XML column is to create the table in which your XML documents will be 


stored. 


Related concepts: 


* “XML Collections as a storage and access method” on page 109 
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* ‘Using the DAD file with XML collections” on page 196 
* “Dad Checker” on page 210 


Related tasks: 


* “Using the DAD checker” on page 211 


Using the DAD file with XML collections 


For XML collections, the DAD file maps the structure of the XML document to 
the DB2® tables from which you compose the document. You can also 
decompose documents to the DB2 tables using the DAD file. 


For example, if you have an element called <Tax> in your XML document, 
you need to map <Tax> to a column called TAX. You use the DAD file to 
define the relationship between the XML data and the relational data. 


You must specify the DAD file either while enabling a collection, or when you 
are using the DAD file in stored procedures for XML collections. The DAD is an 
XML-formatted document, residing at the client. If you choose to validate 
XML documents with a DTD, the DAD file can be associated with that DTD. 
When used as the input parameter of the XML Extender stored procedures, 
the DAD file has a data type of CLOB. This file can be up to 100 KB. 


To specify the XML collection access and storage method, use the 
<Xcollection>tag in your DAD file. 


<Xcollection> 
Specifies that the XML data is either to be decomposed from XML 
documents into a collection of relational tables, or to be composed 
into XML documents from a collection of relational tables. 


An XML collection is a set of relational tables that contains XML data. 
Applications can enable an XML collection of any user tables. These 
user tables can be tables of existing business data or tables that the 
XML Extender recently created. 


The DAD file defines the XML document tree structure, using the following 
kinds of nodes: 


root_node 
Specifies the root element of the document. 


element_node 
Identifies an element, which can be the root element or a child 
element. 
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text_node 
Represents the CDATA text of an element. 


attribute_node 
Represents an attribute of an element. 


Figure 14)shows a fragment of the mapping that is used in a DAD file. The 
nodes map the XML document content to table columns in a relational table. 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM ""dxxsamples\dtd\dad.dtd"> 
<DAD> 


<Xcollection> 
<SQL_stmt> 


</SQL_stmt> 

<prolog>?xml version="1.0"?</prolog> 

<doctype>!DOCTYPE Order SYSTEM 
""dxxsamples\dtd\getstart.dtd""</doctype> 

<root_node> 


<element_node name="0rder"> --> Identifies the element <Order> 
<attribute_node name="key"> --> Identifies the attribute "key" 
<column name="order_key"/> --> Defines the name of the column, 


"order_key", to which the 
element and attribute are 
mapped 

</attribute_node> 

<element_node name="Customer"> --> Identifies a child element of 
<Order> as <Customer> 


<text_node> --> Specifies the CDATA text for 
the element <Customer> 
<column name="customer"> --> Defines the name of the column, 


"customer", to which the child 
element is mapped 

</text_node> 

</element_node> 


</element_node> 
</root_node> 
</Xcollection> 
</DAD> 
Figure 14. Node definitions for the XML document as mapped to the XML collection table 


In this example, the first two columns have elements and attributes mapped 
to them. 
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You can use the XML Extender administration wizard or an editor to create 
and update the DAD file. 


Related concepts: 


* |’Mapping schemes for XML collections” on page 125 


SQL composition 


You can compose XML documents using columns with the same name. 
Selected columns with the same name, even if from diverse tables, must be 
identified by a unique alias so that every variable in the select clause of the 
SQL statement is different. The following example shows how you would give 
columns that have the same names unique aliases. 
<SQL_stmt>select o.order_key as oorder_key, 
key customer_name, customer_email, 
p.part_key p.order_key as porder_key, 
color, qty, price, tax, ship_id, date, mode 
from order_tab o.part_tab p 
order by order_key, part_key</SQL_stmt> 


You can also compose XML documents using columns with random values. If 
an SQL statement in a DAD file has a random value, you must give the 
random value function an alias to use it in the ORDER BY clause.This 
requirement is because the value is not associated with any column in a table. 
See the alias for Generate_unique at the end of the ORDER BY clause in the 
following example. 
<SQL_stmt>select o.order_key, customer_name,customer_email, 
p.part_key,color,qty,price,tax,ship_id, 
date, mode 
from order_tab o,part_tab p, 
table(select substr(char(timestamp(generate_unique())),16) 
as ship_id, date, mode, 
part_key 
from ship_tab) s 
where o.order_key=1 and p.price>2000 and 
o.order_key=o.order_key and s.part_key 
order by order_key, part_key,ship_id</SQL_stmt> 


RDB node composition 
The following restrictions apply to RDB node composition: 


* The condition associated with any non-root_node RDB node DAD file must 
compare against a literal. 


* The condition associated with a root_node describes the relationship 
between the tables involved in the RDB node composition. For example, a 
primary foreign key relationship. 

* Each equality in the condition associated with a top-level RDB_node 
specifies the join relationship between columns of two tables and is applied 
separately from the other equalities. In other words, all the predicates 
connected by AND do not apply simultaneously for a single join condition, 
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thereby simulating an outer join during document composition. The 
parent-child relationship between each pair of tables is determined by their 
relative nesting in the DAD file. For example: 


<condition>order_tab.order_key=part_tab.order_key AND 
part_tab.part_key=ship_tab.part_key</condition> 


DTD for the DAD file 


This section describes the document type declarations (DTD) for the document 
access definition (DAD) file. The DAD file itself is a tree-structured XML 
document and requires a DTD. The DTD file name is dad.dtd. The following 
example shows the DTD for the DAD file. 


<?xml encoding="US-ASCII"?> 


<!ELEMENT DAD (dtdid?, validation, (Xcolumn | Xcollection))> 
<!ELEMENT dtdid (#PCDATA)> 
<!ELEMENT validation (#PCDATA)> 
<!ELEMENT Xcolumn (table*)> 
<!ELEMENT table (column«)> 
<!ATTLIST table name CDATA #REQUIRED 
key CDATA #IMPLIED 
orderBy CDATA #IMPLIED> 
<!ELEMENT column EMPTY> 
<!ATTLIST column 
name CDATA #REQUIRED 
type CDATA #IMPLIED 
path CDATA #IMPLIED 
multi_occurrence CDATA #IMPLIED> 
<!ELEMENT Xcollection (SQL_stmt?, prolog, doctype, root_node)> 
<!ELEMENT SQL_stmt (#PCDATA)> 
<!ELEMENT prolog (#PCDATA)> 
<!ELEMENT doctype (#PCDATA | RDB_node) *> 
<!ELEMENT root_node (element_node)> 
<!ELEMENT element_node (RDB_nodex, 
attribute_nodex, 
text_node?, 
element_nodex, 
namespace_node*, 
process _instruction_nodex, 
comment_node*)> 
<!ATTLIST element_node 
name CDATA #REQUIRED 
ID CDATA #IMPLIED 
multi_occurrence CDATA "NO" 
BASE_URI CDATA #IMPLIED> 
<!ELEMENT attribute_node (column | RDB_node)> 
<!ATTLIST attribute_node 
name CDATA #REQUIRED> 
<!ELEMENT text_node (column | RDB_node)> 
<!ELEMENT RDB node (table+, column?, condition?)> 
<!ELEMENT condition (#PCDATA)> 
<!ELEMENT comment_node (#PCDATA)> 
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<!ELEMENT namespace_node (EMPTY)> 
<!ATTLIST namespace_node 
name CDATA #IMPLIED 
value CDATA #IMPLIED> 
<!ELEMENT process instruction_node (#PCDATA)> 


The DAD file has four major elements: 
* DTDID 

* validation 

* Xcolumn 


* Xcollection 


Xcolumn and Xcollection have child element and attributes that aid in the 
mapping of XML data to relational tables in DB2. The following list describes 
the major elements and their child elements and attributes. Syntax examples 
are taken from the previous example. 


DTDID element 
DTDs that are provided to the XML Extender are stored in the 
DTD_REF table. Each DTD is identified by a unique ID that is 
provided in the DTDID tag of the DAD file. The DTDID points to the 
DTD that validates the XML documents, or guides the mapping 
between XML collection tables and XML documents. For XML 
collections, this element is required only for validating input and 
output XML documents. For XML columns, this element is needed 
only to validate input XML documents. The DTDID must be the same 
as the SYSTEM ID specified in the doctype of the XML documents. 


Syntax: <!ELEMENT dtdid (#PCDATA)> 


validation element 
Indicates whether or not the XML document is to be validated with 
the DTD for the DAD. If YES is specified, then the DTDID must also be 
specified. 


Syntax: <!ELEMENT validation (#PCDATA)> 


Xcolumn element 
Defines the indexing scheme for an XML column. It is composed of 
zero or more tables. 


Syntax: <!ELEMENT Xcolumn (table*)>Xcolumn has one child element, 
table. 


table element 
Defines one or more relational tables created for indexing elements or 
attributes of documents stored in an XML column. 


Syntax: 
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<!ELEMENT table (column+)> 

<!ATTLIST table name CDATA #REQUIRED 
key CDATA #IMPLIED 
orderBy CDATA #IMPLIED> 


The table element has one mandatory and two implied attributes: 


name attribute 
Specifies the name of the side table 


key attribute 
The primary single key of the table 


orderBy attribute 
The names of the columns that determine the sequence order 
of multiple-occurring element text or attribute values when 
generating XML documents. 


The table element has one child element: 


column element 
Maps an attribute of a CDATA node from the input XML 
document to a column in the table. 


Syntax: 


<!ATTLIST column 
name CDATA #REQUIRED 
type CDATA #IMPLIED 
path CDATA #IMPLIED 
multi_occurrence CDATA #IMPLIED> 


The column element has the following attributes: 


name attribute 
Specifies the name of the column. It is the alias name 
of the location path which identifies an element or 
attribute 


type attribute 
Defines the data type of the column. It can be any 
SQL data type. 


path attribute 
Shows the location path of an XML element or 
attribute and must be the simple location path as 
specified in Table 3.1.a (fix link) . 


multi_occurrence attribute 
Specifies whether this element or attribute can occur 
more than once in an XML document. Values can be 
YES or NO. 
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Xcollection 
Defines the mapping between XML documents and an XML collection 
of relational tables. 


Syntax: 
<!ELEMENT Xcollection(SQL_stmt?, prolog, doctype, root_node)> 


Xcollection has the following child elements: 


SQL_stmt 
Specifies the SQL statement that the XML Extender uses to 
define the collection. Specifically, the statement selects XML 
data from the XML collection tables, and uses the data to 
generate the XML documents in the collection. The value of 
this element must be a valid SQL statement. It is only used for 
composition, and only a single SQL_stmt is allowed. 


Syntax: <!ELEMENT SQL stmt #PCDATA > 


prolog 
The text for the XML prolog. The same prolog is supplied to 
all documents in the entire collection. The value of prolog is 
fixed. 


Syntax: <!ELEMENT prolog #PCDATA> 


doctype 
Defines the text for the XML document type definition. 


Syntax: 
<!ELEMENT doctype (#PCDATA | RDB_node) «> 


doctype is used to specify the DOCTYPE of the resulting 
document. Define an explicit value. This value is supplied to 
all documents in the entire collection. 


doctype has one child element: 


root_node 
Defines the virtual root node. root_node must have one 
required child element, element_node, which can be used only 
once. The element_node under the root_node is actually the 
root_node of the XML document. 


Syntax: <!ELEMENT root_node(element_node)> 


RDB_node 
Defines the DB2 table where the content of an XML element 
or value of an XML attribute is to be stored or from where it 
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will be retrieved. rdb_node is a child element of 
element_node, text_node, and attribute_node and has the 
following child elements: 


table Specifies the table in which the element or attribute 
content is stored. 


column 
Specifies the column in which the element or attribute 
content is stored. 


condition 
Specifies a condition for the column. Optional. 


element_node 
Represents an XML element. It must be defined in the DAD 
specified for the collection. For the RDB_node mapping, the 
root element_node must have an RDB_node to specify all tables 
containing XML data for itself and all of its child nodes. It can 
have zero or more attribute_nodes and child element_nodes, 
as Well as zero or one text_node. For elements other than the 
root element no RDB_node is needed. 


Syntax: 
An element_node is defined by the following child elements: 


RDB_node 

(Optional) Specifies tables, column, and conditions for 
XML data. The RDB_node for an element only needs 
to be defined for the RDB_node mapping. In this case, 
one or more tables must be specified. The column is 
not needed since the element content is specified by 
its text_node. The condition is optional, depending on 
the DTD and query condition. 


child nodes 
(Optional) An element_node can also have the 
following child nodes: 


element_node 
Represents child elements of the current XML 
element 


attribute_node 
Represents attributes of the current XML 
element 


text_node 
Represents the CDATA text of the current 
XML element 
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attribute_node 
Represents an XML attribute. It is the node defining the 
mapping between an XML attribute and the column data in a 
relational table. 


Syntax: 


The attribute node must have definitions for a name attribute, 
and either a column or a RDB_node child element. 
attribute_node has the following attribute: 


name The name of the attribute. 


attribute_node has the following child elements: 


Column 
Used for the SQL mapping. The column must be 
specified in the SELECT clause of SQL_stmt. 


RDB_node 
Used for the RDB_node mapping. The node defines 
the mapping between this attribute and the column 
data in the relational table The table and column must 
be specified. The condition is optional. 


text_node 
Represents the text content of an XML element. It is the node 
defining the mapping between an XML element content and 
the column data in a relational table. 


Syntax: It must be defined by a column or an RDB_node child 
element: 


Column 
Needed for the SQL mapping. In this case, the column 
must be in the SELECT clause of SQL_stmt. 


RDB_node 
Needed for the RDB_node mapping. The node defines 
the mapping between this text content and the column 
data in the relational table. The table and column 
must be specified. The condition is optional. 


Related concepts: 


* \“Using the DAD file with XML collections” on page 196 


Related tasks: 


* |“Dynamically overriding values in the DAD file” on page 205 
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Dynamically overriding values in the DAD file 
Procedure: 


For dynamic queries you can use two optional parameters to override 
conditions in the DAD file: override and overrideType. Based on the input from 
overrideType, the application can override the <SQL_stmt> tag values for SQL 
mapping or the conditions in RDB_nodes for RDB_node mapping in the 
DAD. 


These parameters have the following values and rules: 


overrideType 
This parameter is a required input parameter (IN) that flags the type of 
the override parameter. The overrideType parameter has the following 
values: 


NO_OVERRIDE 
Specifies not to override a condition in the DAD file. 


SQL_OVERRIDE 
Specifies to override a condition in DAD file with an SQL statement. 


XML_OVERRIDE 
Specifies to override a condition in the DAD file with an XPath-based 
condition. 


override 

This parameter is an optional input parameter (IN) that specifies the 

override condition for the DAD file. The syntax of the input value 

corresponds to the value specified on the overrideType parameter: 

* If you specify NO_OVERRIDE, the input value is a NULL string. 

* If you specify SQL_OVERRIDE, the input value is a valid SQL 
statement. 
If you use SQL_OVERRIDE as an SQL statement, you must use the SQL 
mapping scheme in the DAD file. The input SQL statement overrides 
the SQL statement specified by the <SQL_stmt> element in the DAD 
file. 

* If you specify XML_OVERRIDE, the input value is a string that 
contains one or more expressions. 
If you use XML_OVERRIDE and an expression, you must use the 
RDB_node mapping scheme in the DAD file. The input XML expression 
overrides the RDB_node condition specified in the DAD file. The 
expression uses the following syntax: 
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AND: 


p>>—v 


simple location path 


This syntax has the following components: 


simple location path 
Specifies a simple location path, using syntax defined by XPath.. 


operators 
The SQL operators shown in the syntax diagram can have a space 
to separate the operator from the other parts of the expression. 


Spaces around the operators are optional. Spaces are mandatory 
around the LIKE operator. 


value 
A numeric value or a string enclosed in single quotation marks. 


AND 
And is treated as a logical operator on the same location path. If a 
simple location path is specified more than once in the override 
string, then all the predicates for that simple location path are 
applied simultaneously. 


If you specify XML_OVERRIDE, the condition for the RDB_node in the 
text_node or attribute_node that matches the simple location path is 
overridden by the specified expression. 


XML_OVERRIDE is not completely XPath compliant. The simple 
location path is used only to identify the element or attribute that is 
mapped to a column. 


The following examples use SQL_OVERRIDE and XML_OVERRIDE to show 
dynamic override. 


Example 1: A stored procedure using SQL_OVERRIDE. In this example, the 
<xcollection> element in the DAD file must have an <SQL_stmt> element. 
The override parameter overrides the value of <SQL_stmt>, by changing the 
price to be greater than 50.00, and the date to be greater than 1998-12-01. 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 
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EXEC SQL BEGIN DECLARE SECTION; 

char collectionName[32]; /* name of an XML collection */ 

char result_tab[32]; /* name of the result table */ 

char result_colname[32]; /* name of the result column */ 

char valid_colname[32]; /* name of the valid column, will set to NULL*/ 


char override[512] ; /* override «/ 

short overrideType; /* defined in dxx.h */ 

short max_row; /* maximum number of rows */ 
short num_row; /* actual number of rows */ 
long returnCode; /* return error code */ 


char returnMsg[1024] ; /* error message text */ 
short  collectionName_ind; 
short rtab_ind; 

short rcol_ind; 

short vcol_ind; 

short ovtype_ind; 

short  ov_ind; 

short maxrow_ind;+ 

short numrow_ind; 

short returnCode_ind; 

short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 
float price_value; 


/* create table */ 
EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initial host variable and indicators */ 
strcpy(collection, "sales_ord"); 
strcpy(result_tab,"xml_order_tab"); 
strcpy(result_col,"xmlorder") ; 
valid_colname[0] = '\0'; 


/* get the price_value from some place, such as from data */ 
price_value = 1000.00 /* for example */ 


/* specify the override */ 
sprintf (override, 
" SELECT o.order_key, customer, p.part_key, 
quatity, price, tax, ship_id, date, mode 
FROM order_tab o, part_tab p, 
table(select db2xml.generate_unique() 
as ship_id, date, mode from ship_tab) s 
WHERE p.price > %d and s.date >'1996-06 01' AND 
p.order_key = o.order_key and s.part_key = p.part_key", 
price_value); 


overrideType = SQL_OVERRIDE; 
max_row = 0; 

num_row = 0; 

returnCode = 0; 

msg_txt[0] = '\0'; 
collectionName_ind = 0; 
rtab_ind = 0; 

rcol_ind = 0; 
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vcol_ind = -1; 
ov_ind = 0; 

ovtype_ind = 
maxrow_ind 
numrow_ind = 
returnCode_in - 
returnMsg_ind = -1; 


iT} 
a1, oe 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXRETRIEVEXML" (:collectionName:collectionName_ind, 
sresult_tab:rtab_ind, 
sresult_colname:rcol_ind, 
:valid_colname:vcol_ind, 
:overrideType:ovtype_ind, :override:ov_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
sreturnCode:returnCode_ind, 

:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


Example 2: A stored procedure using XML_OVERRIDE. In this example, the 
<collection> element in the DAD file has an RDB_node for the root 
element_node. The override value is XML-content based. The XML Extender 
converts the simple location path to the mapped DB2 column. 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 

EXEC SQL BEGIN DECLARE SECTION; 

char collectionName[32]; /* name of an XML collection */ 

char result_tab[32]; /* name of the result table */ 

char result_colname[32]; /* name of the result column */ 

char valid_colname[32]; /* name of the valid column, will set to NULL*/ 


char override [256] ; /* override, SQL_stmt*/ 
short overrideType; /* defined in dxx.h */ 
short max_row; /* maximum number of rows */ 
short num_row; /* actual number of rows */ 
long returnCode; /* return error code */ 


char returnMsg[1024]; /* error message text */ 
short  collectionName_ind; 
short rtab_ind; 

short  rcol_ind; 

short  vcol_ind; 

short ovtype_ind; 

short  ov_ind; 

short maxrow_ind; 

short numrow_ind; 

short returnCode_ind; 

short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 
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/* create table */ 


EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initial host variable and indicators */ 


strcpy(collection, "sales_ord"); 
strcpy(result_tab,"xml_order_tab"); 
strcpy(result_col,"xmlorder") ; 
valid_colname[0] = '\0'; 

sprintf (override,"%s %s", 


"/Order/Part Price > 50.00 AND ", 
"/Order/Part/Shipment/ShipDate > '1998-12-01'"); 


overrideType = XML_OVERRIDE; 
max_row = 500; 

num_row = 0; 

returnCode = 0; 

msg_txt[0] = '\0'; 
collectionName_ind = 0; 
rtab_ind 
rcol_ind 
vcol_ind 
ov_ind = Q; 
ovtype_ind = 0; 
maxrow_ind = 0 
numrow_ind 
returnCode_ind = -1; 
returnMsg_ind = -1; 


iT} 
bo we 
we 


/* Call the store procedure */ 
EXEC SQL CALL "DB2XML.DXXRETRIEVE" 


(:collectionName:collectionName_ind, 


:result_tab:rtab_ind, 


:result_colname:rcol_ind, 


:valid_colname:vcol_ind, 


:overrideType:ovtype_ind, :override:ov_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode:returnCode_ind,:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


Related concepts: 


* (Using the DAD file with XML collections” on page 196 


* |“Dad Checker” on page 210 


Related tasks: 


* |Creating a DAD file for XML columns” on page 193 
* {Using the DAD checker” on page 211 
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Related reference: 


* “DTD for the DAD file” on page 199 


Dad Checker 


The Document Access Definition (DAD) file is an XML file that is supported 
in DB2® XML Extenders. The DAD associates XML documents to DB2 
database tables through two alternative access and storage methods: XML 
columns and XML collections. XML collection enables the decomposition 
(storage) of data from XML documents into DB2 relational tables and the 
composition of XML documents from relational data. The DAD file is used to 
specify how XML documents are to be stored or composed. The DAD checker 
can only be used to verify the validity of DAD files that use the XML 
collection storage method. In such a file, a mapping scheme that specifies the 
relationship between the tables and the structure of the XML document is 
specified. 


Much like Document Type Descriptions (DTDs) are used to validate the 
syntax of XML documents, the DAD checker is used to ensure that a DAD file 
is semantically correct. This validation can take place without connecting to a 
database. Use of the DAD checker can help minimize the number of errors 
that occur when submitting the file to the XML Extender for processing. The 
DAD checker is a Java’” application that is called from the command line. 
When invoked, it produces a set of two output files that contain errors, 
warnings and success indicators. The two files are equivalent; one is a plain 
text file that you use to check for errors or warnings; the other is an XML file, 
“errorsOutput.xml’, which communicates the results of the DAD checker 
application to other applications. The name of the output text file is 
user-defined. If no name is specified, the standard output is used. 


Related concepts: 


* \“Using the DAD file with XML collections” on page 196 


Related tasks: 


* |“Dynamically overriding values in the DAD file” on page 205 


“Creating a DAD file for XML columns” on page 193) 
“Using the DAD checker” on page 211 
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Using the DAD checker 


Prerequisites: 


You must have a JRE or JDK Version 1.3.1 or later installed on your system. 


Procedure: 


To use the DAD checker: 


1. 


Download the DADChecker.zip file, and extract all files into a directory of 
your choice. 


. From a command line change to the /bin subdirectory in the directory 


where you installed the DAD checker. 


Set the classpath by running the setCP.bat file, located in the bin directory. 
Execute the following command: 

java dadchecker.Check_dad_xml [-dad | -xm1] [-al1][-tag tagname] 

[-out outputFile] fileToCheck 

Where: 


¢ -dad indicates that the file that is to be checked is a DAD file. This is the 
default option. 


* -xml indicates that the file that is to be checked is an XML document 
rather than a DAD file. For large XML documents, the Java Virtual 
Machine might run out of memory, producing a java.lang. 
OutOfMemoryError exception. In such cases, the -Xmx option can be 
used to allocate more memory to the Java Virtual Machine. Refer to the 
JDK documentation for details. 


* -all indicates that the output will show all occurrences of tags that are 
in error. 


* -tag indicates that only the duplicate tags whose name attribute values 
are tagname are displayed. For XML documents, only the duplicate tags 
whose name are tagname are displayed. 


* -out outputFile specifies the output text file name. If omitted, the 
standard output is used. A second output file, errorsOutput.xml is also 
created in the same directory as the DAD file. This file is always 
generated and contains in XML form the same information as the output 
text file except the parser warnings and errors. 


To display command line options, type java dadchecker.Check_dad_xml help. 


To display version information, type java dadchecker.Check_dad_xml version. 


Sample files: 
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The following sample files can be found in the samples directory: 
* bad_dad.dad: sample DAD file demonstrating all possible semantic errors. 


* bad_dad.chk: output text file generated by the DAD checker for 
bad_dad.dad. 


* bad_dad.chk: output text file generated by the DAD checker for 
bad_dad.dad. 


* errorsOutput.xml: output XML file generated by the DAD checker for 
bad_dad.dad. 


* dup.xsl: XSL stylesheet used for transforming the errorsOutput.xml file into 
an HTML file showing only the duplicate tags. 


* dups.html: generated HTML file showing only the duplicate tags contained 
in bad_dad.dad. 


Errors and warnings in the output text file: 


Errors and warnings are indicated by tag occurrence. Two tags are considered 
as occurrences of the same tag if: 


* Their name attributes have the same value. 

* They have the same number of ancestors. 

* The name attributes of their corresponding ancestor tags have the same 
value. 


Occurrences of the same tag could potentially have different children tags. 


Tag occurrences that do not conform to the DAD semantic rules are indicated 
in the output text file in the following way: 


* All ancestor tags and their attributes are displayed in sequence. 


* The tag that is in error is displayed, preceded by a number indicating its 
depth in the XML tree. The tag name is followed by a list of line numbers 
where all occurrences of the tag appear in the DAD file. You can display 
each error occurrence separately by using the -all command line option. 

* The direct children tags of the first tag occurrence are displayed. For those 
children tags that specify a data mapping, the data mapping tags are also 
displayed. You can use the -all command line option to display each error 
occurrence separately. 


Example of an error report: 
In this example, the element_node tag whose name attribute has the value 


"Password" is in error. There are two occurrences of this tag in the DAD file, 
one on line 49, and one on line 75. The tag in error can be isolated from the 
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list of ancestor and children tags by locating the tag’s depth indicator (in this 
example 4). The list of ancestor and children tags help establish the context in 
which the error occurred. 
<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 

4  <element_node name="Password"> line(s): 49 75 

<element_node name="Pswd1"> 

<element_node name="Pswd2"> 


If you had used the all option, the output text file would look like this: 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4  <element_node name="Password"> line: 49 
<element_node name="Pswd1"> 
<element_node name="Pswd2"> 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4 <element_node name="Password"> line: 75 
<element_node name="Pswd1"> 
<element_node name="Pswd3"> 


In this example, two occurrences have identical ancestors and name attribute 
values, but different children elements. 

Checks performed by the DAD checker 
When you invoke the DAD checker you receive the following message: 
Checking DAD document: file_path 


where file_path is the path to the DAD file being validated. 


The DAD checker performs the following validation checks: 

1. Well-formedness checking and DTD validation. 

2. Duplicate <attribute_node> and leaf <element_node> detection (RDB_node 
mapping). 

Missing type attribute detection. 

Missing table declaration detection. 

Missing <text_node> or <attribute_node> detection. 

<attribute_node> and <element_node> mapping order check. 


SEO 


Data mapping consistency check for tags with identical name attribute 
values. 
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8. Multi_occurrence attribute value checking for parent <element_node> with 
mapped children (RDB_node mapping). 


9. Attribute and element potential naming conflict check (XML documents). 
These validation checks are described in the following sections: 


Well-formedness and DTD validation 
DAD files must be validated against the DAD DTD, which is located in 


"dxxsamples\dtd\dad.dtd" If the DAD file is not well-formed or if the DTD 
cannot be found, a fatal error occurs that causes the DAD checker to 
terminate, and is indicated in the output text file. For example: 


org.xml.sax.SAXException: Stopping after fatal error, 
line 1, col 22. The XML declaration must end with "?>", 


Validation errors and warnings are also reported in the output text file, but do 
not cause the DAD checker to terminate. The following example is a fragment 
of an output text file showing two possible validation errors that can be 
encountered while parsing the DAD file: 


** The document is not valid against the DTD, line 5, col 15. Element type 
"XCollection" must be declared 


** The document is not valid against the DTD, line 578, col 21. The content of 
element type "text_node" must match "(column|RDB_node)". 


Duplicate <attribute_node> and leaf <element_node> detection 
(RDB_node mapping) 
This check is relevant only to DAD files that use RDB_node mapping. 


Two elements are considered to be duplicates if two or more <attribute_node> 
or <element_node> tags have the same value in their name attribute and they 
have the same ancestor. 


Two or more tags are considered to have the same ancestors if the name 
attributes of their corresponding ancestor tags have the same value. 


A leaf <element_node> is an element_node that is used to map a tag that has 
no children in the XML document tree. Therefore, leaf <element_node> tags 
must have one text node tag as one of their direct children. No other 
<element_node> tags can have text node tags as direct children. 

This conflict may arise either between two or more leaf <element_node> tags, 
two or more <attribute_node> tags or between leaf <element_node> tags and 
<attribute_node> tags. 


Examples: 


Example 1: 
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Leaf <element_node> conflict: 


<element_node name = "Al"> 
<element_node name = "B"> 
<element_node name = "C"> 
<text_node 


<element_node name = "A2"> 
<element_node name = "B"> 
<element_node name = "C"> 
<text_node> 


</element_node> 


In this example, <element_node name = "C"> is duplicated, because it is 


mapped through two different paths: \A1\B\C and \A2\B\C. Note that 


<element_node name="B"> is not considered to be duplicated, because it is a 


non-leaf <element_node>. 


Example 2: 


This example shows an <attribute node> conflict. 


<element_node name = "Al"> 
<attribute_node name = "B"> 


<element_node name = "A2"> 
<attribute_node name = "B"> 

/element_node> 

< 


In this example, <attribute_node name = "B"> is duplicated, because it is 


mapped through two different paths: \A1\B and \A2\B. 


Example 3: 


This example shows a leaf <element_node> and <attribute_node> conflict. 


<element_node name = "A"> 
<element_node name = "B"> 
<text_node> 


</element_node> 
</element_node> 


<attribute_node name = "B"> 


<attribute_node name = "A"> 


Chapter 9. Document access definition (DAD) files 


215 


In this example, <element_node name = "B"> conflicts with <attribute_node 
name = "B">. Note that <element_node name = "A"> and <attribute_node 
name = "A"> do not conflict, because <element_node name = "A”> is not a 
leaf <element_node>. 


If conflicts occur, the XML document DTD must be revised to eliminate the 
conflicts. The XML document and the DAD file also need to be revised to 
reflect the DTD changes. 


Example 4: 


7 duplicate naming conflicts were found 
A total of 16 tags are in error (cumulate occurrences of these tags: 20) 


The following tags are duplicates: 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4 <element_node name="Country"> line(s): 127 135 
<text_node> 
<RDB_node> 
<table name="advertiser"> 
<column type="VARCHAR(63)" name="country"> 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
<element_node name="Campaign" multi_occurrence="YES"> 
<element_node name="Target" multi_occurrence="YES"> 
<element_node name="Location" multi_occurrence="YES"> 
7 <element_node name="Country"> line(s): 460 
<text_node> 
<RDB_node> 
<table name="target_location"> 
<column type="VARCHAR(63)" name="country"> 


Tags that are in error are grouped by naming conflict. The groups are 
separated by lines, and the tags are separated by short lines. You can also 
display all the error occurrences by using the all command line option. 


If there are no duplicates in the DAD file, the following message is written in 
the output text file: 


No duplicated tags were found. 

Missing type attribute detection 

When using a DAD file to enable a collection or for decomposition, the type 
attribute must be specified for each <column> tag. For example: 
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<column name="email" type="varchar(20) "> 


The enable_collection command uses the column type specifications to create 
the tables in the collection if the tables do not exist. If the tables do exist, the 
type specified in the DAD must match the actual column type in the database. 


Example: 


The following example is a fragment of an output text file showing <column> 
tags that do not have the type attribute: 
If this DAD is to be used for decomposition or for enabling a collection, 
the type attributes are missing for the following <column> tag(s): 
<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
<element_node name="Address"> 
<text_node> 
<RDB_node> 
7 <column name="address"> line: 86 


If no type attributes are missing, the following message is written in the 
output text file: 


No type attributes are missing for <column> tags. 


Missing table declaration detection 
The first <RDB_node> tag in the DAD file must enclose the table declaration, 


including all <table> tags which declare the relational tables that are used for 
data mapping. This tag must be enclosed in the first <element_node> tag. All 
subsequent <RDB_node> tags must be enclosed in a <text_node> tag. 


An error is also added to the output file if the first encountered <RDB_node> 
tag contains a <column> tag. This error indicates either that the table 
declaration is missing, or that the table declaration wrongly contains a 
<column> tag. 


Missing <text_node> or <attribute_node> detection 
Each <RDB_node> tag other than the first one, which is used for the table 


declaration, must be enclosed in an <attribute_node> or a <text_node> tag. 
Examples: 

Example 1: 

<element_node name ="amount"> 


<text_node> 
<RDB_node> 
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<table name="fakebank.payments"/> 

<column name="amount" type="decimal (8,2) "/> 
</RDB_node> 

</element_node> 


Example 2: 


The following example is a fragment of an output text file showing a missing 
<text_node> or <attribute_node> tag: 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
<element_node name="PostalCode"> 
5 <RDB_node> line: 107 
<table name="advertiser"> 
<column type="VARCHAR(10)" name="postal_code"> 


Check for <attribute_node> and <element_node> mapping order 

This check is required for FixPak 3 and earlier. The <attribute_node> tags 
need to be mapped to a table before any <element_node> tags are mapped to 
the table. 


Example: 


The following example shows tags that need to be mapped to a table. 


<element_node name="payment-request" 
multi_occurrence="YES"> 
<element_node name="payment-request-id"> 
<text_node> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="statement_id" type="varchar (30) "/> 


<element_node name="bank-customer-info"> 
<element_node name="account"> 
<attribute_node name="type"> 
<text_node> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="payor_account" type="char(6)"/ 


In this example, <attribute_node name="type”> is mapped to the same table 
(fakebank.payments) as <element_node name = "payment-request-id”>. The 
mapping of the <attribute_node> must precede the mapping of the 
<element_node>. 


218 Administration and Programming for iSeries 


fat mapping consistency check for tags with identical name attribute 

values 

Within the DAD file, all <element_node> tags and all <attribute_node> tags 
that are mapped and, identified by distinct name attribute values should be 
mapped only once. If two or more occurrences of an <element_node> tag or 
<attribute_node> tag are mapped to different columns, their name attributes 
should be assigned different values. 


Example: 


Example 1: In this example, the second occurrence of the <element_node 
name="type”> tag has a different mapping than the first occurrence. Duplicate 
<attribute_node> and duplicate leaf <element_node> tags are not displayed as 
a result of this check. 


<element_node name="bank-customer-info"> 
<element_node name="account"> 
<element_node name="type"> 
<text_node> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="payor_account" type="char(20) 
</RDB_node> 
</text_node> 
</element_node> 
<element_node> 
<element_node> 
<element_node name="bank-customer-info"> 
<element_node name="account"> 
<element_node name="type"> 
<text_node> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="payto_account" type="char(20)"/> 
</RDB_node> 
</text_node> 
</element_node> 
</element_node> 
<element_node> 


You can fix this error by creating a new element to use with the second 
mapping. You also need to change the DTD, the XML document, and the 
DAD file. 


Example 2: This example is a fragment of an output text file that indicates 
<element_node> tags that have the same names and ancestors, but not the 
same mappings. 
<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4 <element_node name="PostalCode"> line(s): 127 
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<text_node> 

<RDB_node> 

<table name="advertiser"> 

<column type="VARCHAR(10)" name="postal_code"> 


<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4 <element_node name="PostalCode"> line(s): 135 143 
<text_node> 
<RDB_node> 
<table name="advertiser"> 
<column type="VARCHAR(10)" name="postal_code2"> 


In this example, one occurrence of the <element_node name="PostalCode”> 
on line 127 is mapped to the ‘postal_code’ column, and two other occurrences 
of the same tag, on lines 135 and 143, are mapped to the ‘postal_code2’ 
column. 


Multi_occurrence attribute value checking for parent <element_node> 
with mapped children 
This check is relevant only to DAD files that use RDB-node mapping. 


The default value for the multi_occurrence attribute is NO. The 
multi_occurrence attribute should be assigned the value YES for each 
<element_node> tag that has as direct children an <attribute_node> tag or 
two or more <element_node> tags meeting one or two of the following 
criteria: 


* the <element_node> is mapped ( it has a <text_node> as its direct child) 
¢ the <element_node> has at least one <attribute_node> as a direct child 


Example: 


Example 1: In the following example, payment-request-id and amount are 
mapped to a DB2 table. Sender has an <attribute_node> as a direct child. 
Payment-request-id, amount and sender are all direct children of 
payment-request: 


<element_node name="payment-request" multi_occurrence="YES"> 
<element_node name="payment-request-id"> 
<text_node> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="statement_id" type="varchar(30)"/> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name ="amount"> 
<text_node> 
<RDB_node> 
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<table name="fakebank.payments"/> 
<column name="amount" type="decimal (8,2) "/> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name ="sender"> 
<attribute_node name ="ID"> 
<RDB_node> 
<table name="fakebank.payments"/> 
<column name="sender_ID" type="decimal (8,2)"/> 
</RDB_node> 
</attribute_node> 
</element_node> 
</element_node> 


The DAD checker indicates all <element_node> tags whose multi_occurrence 
attributes are set to NO. 


Example 2: The following example is a fragment of an output text file 
suggesting <element_node> tags whose multi_occurrence attributes should be 
set to YES. 
<DAD> 
<Xcollection> 
<root_node> 
<element_node name="Advertiser" multi_occurrence="YES"> 
4 <element_node name="Password"> Jline(s): 49 75 
<element_node name="Pswd1"> 
<element_node name="Pswd2"> 


Attribute and element naming conflict 


In XML documents, elements with the same name can appear in different 
contexts, such as having different ancestor elements. Attributes and elements 
can have identical names. The XML Extender is currently unable to resolve 
these naming conflicts because they result in duplicate tags in the DAD file. 
Therefore all attributes and all elements with the same ancestors that are to be 
mapped must have unique names. 


The DAD checker can be used to check XML documents for naming conflicts. 
If more than one of the conflicting elements or attributes needs to be mapped, 


then naming changes should be made to the document and the DTD. 


It is best to check the XML document before the DAD file is created. The 
DAD checker does not validate the XML document against its DTD. 


Example: 


The following example is a fragment of an XML document where naming 
conflicts occur: 
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<Al> 
<B> 
<C> 


<A2> 
<B> 
<C> 


<D C="attValue"> 


eee 


If the <C> element and the C attribute are to be mapped, then the resulting 
DAD file would have the following duplicate conflicts: 
<element_node name = "Al"> 
<element_node name = "B"> 
<element_node name = "C"> 
<text_node> 
<element_node name = "A2"> 
<element_node name = "B"> 
<element_node name = "C"> 
<text_node> 


<element_node name = "D"> 
<attribute_node name = "C"> 


</element_node> 


The two <element_node name = "C"> tags and the <attribute_node name = 
"C"> tag are duplicates in the DAD. 
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Chapter 10. XML Extender stored procedures 


Stored procedures introduction 


The XML Extender provides stored procedures (also called procedures) for 
administration and management of XML columns and collections. These 
stored procedures can be called from the DB2 client. The client interface can 
be embedded in SQL, ODBC, or JDBC. Refer to the section on stored 
procedures in the DB2 UDB for iSeries SQL Programming for details on how to 
call stored procedures. 


The stored procedures use the schema DB2XML, which is the schema name of 
the XML Extender. 


The XML Extender provides three types of stored procedures: 


* Administration stored procedures, which assist users in completing 
administrative tasks 


* Composition stored procedures, which generate XML documents using data 
in existing database tables 


* Decomposition stored procedures, which break down or shred incoming 
XML documents and store data in new or existing database tables 


Before calling stored procedures, you must follow the set up procedures for 
all environments. Sample programs that call stored procedures are located in 
DXXSAMPLES/QCSRC. 

Specifying include files for XML Extender stored procedures 


Ensure that you include the XML Extender external header files in the 
program that calls stored procedures. The header files are located in the 
"dxxsamples\include” directory. The header files are: 


dxx.h The XML Extender defined constant and data types 


dxxre.h The XML Extender return code 
The syntax for including these header files is: 
#include "dxx.h" 


#include "dxxrc.h" 


Make sure that the path of the include files is specified in your makefile with 
the compilation option. 
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XML Extender administration stored procedures 


These stored procedures are used for administration tasks, such as enabling or 
disabling an XML column or collection. They are called by the XML Extender 
administration wizard and the administration command dxxadm. These stored 
procedures are: 


* dxxEnableDB() 

* dxxDisableDB() 

* dxxEnableColumn() 

* dxxDisableColumn() 

* dxxEnableCollection() 
* dxxDisableCollection() 


dxxEnableDB() 
Purpose: 


Enables the database. When the database is enabled, the XML Extender 
creates the following objects: 


* The XML Extender user-defined types (UDTs). 
* The XML Extender user-defined functions (UDFs). 


¢ The XML Extender DTD reference table, DTD_REF, which stores DTDs and 
information about each DTD. 


* The XML Extender usage table, XML_USAGE, which stores common 
information for each column that is enabled for XML and for each 


collection. 
Syntax: 
dxxEnableDB(char(dbName) dbName, /* input */ 
long returnCode, /* output */ 


varchar(1024) returnMsg) /* output */ 


Parameters: 


Table 47. dxxEnableDB() parameters 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
returnCode The return code from the stored OUT 
procedure. 
returnMsg The message text that is returned |OUT 
in case of error. 
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Related concepts: 


* (Chapter 11, “XML Extenders administration support tables” on page 251 


Related tasks: 


* |‘Enabling a database for XML” on page 68 


* \“Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* XML Extender administration stored procedures” on page 224, 


* |‘How to read syntax diagrams” on page xi 


dxxDisableDB() 


Purpose: 


Disables the database. When the XML Extender disables the database, it drops 


the following objects: 
* The XML Extender user-defined types (UDTs). 
* The XML Extender user-defined functions (UDFs). 


¢ The XML Extender DTD reference table, DTD_REF, which stores DTDs and 


information about each DTD. 


* The XML Extender usage table, XML_USAGE, which stores common 
information for each column that is enabled for XML and for each 


collection. 


Important: You must disable all XML columns before attempting to disable a 
database. The XML Extender cannot disable a database that contains columns 


or collections that are enabled for XML. 


Syntax: 

dxxDisab1eDB (char (dbName) dbName, /* input */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 

Parameters: 


Table 48. dxxDisableDB() parameters 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
returnCode The return code from the stored OUT 

procedure. 
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Table 48. dxxDisableDB() parameters (continued) 


Parameter Description IN/OUT parameter 


returnMsg The message text that is returned |OUT 
in case of error. 


Related concepts: 
* (Chapter 11, “XML Extenders administration support tables” on page 251 


Related tasks: 
* |“Calling XML Extender composition stored procedures” on page 230 


Related reference: 
* “XML Extender administration stored procedures” on page 224 


* “How to read syntax diagrams” on page xi 


dxxEnableColumn() 


Purpose: 


Enables an XML column. When enabling a column, the XML Extender 
completes the following tasks: 


* Determines whether the XML table has a primary key; if not, the XML 
Extender alters the XML table and adds a column called DXXROOT_ID. 


* Creates side tables that are specified in the DAD file with a column 
containing a unique identifier for each row in the XML table. This column 
is either the root_id that is specified by the user, or it is the DXXROOT_ID 
that was named by the XML Extender. 


* Creates a default view for the XML table and its side tables, optionally 
using a name you specify. 


Syntax: 
dxxEnableColumn(char(dbName) dbName, /* input */ 
char(tbName) tbName, /* input */ 
char(colName) colName, /* input */ 
CLOB (100K) DAD, /* input */ 
char(defaultView) defaultView, /* input */ 
char(rootID) rootID, /* input */ 
long returnCode, /* output */ 


varchar(1024) returnMsg) /* output */ 
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Parameters: 


Table 49. dxxEnableColumn() parameters 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
tbName The name of the table containing | IN 
the XML column. 
colName The name of the XML column. IN 
DAD A CLOB containing the DAD file. | IN 
defaultView The name of the default view IN 
joining the application table and 
side tables. 
rootID The name of the single primary IN 
key in the application table that is 
to be used as the root ID for the 
side table. 
returnCode The return code from the stored |OUT 
procedure. 
returnMsg The message text that is returned |OUT 


in case of error. 


Related concepts: 


* “XML Columns as a storage access method” on page 92 


Related tasks: 


* |“Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* “XML Extender administration stored procedures” on page 224, 
* |‘How to read syntax diagrams” on page xi 


dxxDisableColumn() 


Purpose: 


Disables the XML-enabled column. When an XML column is disabled, it can 
no longer contain XML data types. 


Syntax: 
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dxxDisableColumn(char(dbName) dbName, /* input */ 
char(tbName) tbName, /* input */ 
char(colName) colName, /* input */ 


long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 


Parameters: 


Table 50. dxxDisableColumn() parameters 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
tbName The name of the table containing |IN 
the XML column. 
colName The name of the XML column. IN 
returnCode The return code from the stored |OUT 
procedure. 
returnMsg The message text that is returned |OUT 
in case of error. 


dxxEnableCollection() 


Purpose: 


Enables an XML collection that is associated with an application table. 


Syntax: 


dxxEnableCollection(char(dbName) dbName, 


Parameters: 


/* input */ 
char(colName) colName, /* input */ 
CLOB(100K) DAD, /* input */ 


returnCode, /* output */ 


Table 51. dxxEnableCollection() parameters 


varchar(1024) returnMsg) /* output */ 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
colName The name of the XML collection. | IN 
DAD A CLOB containing the DAD IN 
file. 
returnCode The return code from the stored |OUT 


procedure. 
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Table 51. dxxEnableCollection() parameters (continued) 


Parameter Description IN/OUT parameter 


returnMsg The message text that is returned | OUT 
in case of error. 


Related concepts: 


* (“XML Collections as a storage and access method” on page 109 


Related tasks: 


* “Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* (XML Extender administration stored procedures” on page 224 
* “How to read syntax diagrams” on page xi 


dxxDisableCollection() 
Purpose: 


Disables an XML-enabled collection, removing markers that identify tables 
and columns as part of a collection. 


Syntax: 

dxxDisableCollection(char(dbName) dbName, /* input */ 
char(colName) colName, /* input */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 

Parameters: 


Table 52. dxxDisableCollection() parameters 


Parameter Description IN/OUT parameter 
dbName The database name. IN 
colName The name of the XML collection. | IN 
returnCode The return code from the stored |OUT 
procedure. 
returnMsg The message text that is returned |OUT 
in case of error. 
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XML Extenders composition stored procedures 


The composition stored procedures dxxGenXML() and dxxRetrieveXML() are 
used to generate XML documents using data in existing database tables. The 
dxxGenXML() stored procedure takes a DAD file as input; it does not require 
an enabled XML collection. The dxxRetrieveXML() stored procedure takes an 
enabled XML collection name as input. 


The following performance enhancements have been made for composition 
stored procedures. 


* On iSeries and zSeries operating systems, the length of the override 
parameter has been increased to 16KB.On iSeries and zSeries operating 
systems, the length of the override parameter has been increased to 16KB. 


* The requirement for an intermediate result table has been removed. 
* By using these stored procedures: 


— You reduce the instruction path length because there is no need to create 
result tables. 


— You simplify your programming. 
* Use the stored procedures that require an intermediate result table if you 
want to produce more than one document. 


¢ The user-defined functions for XML column have been enhanced for 
performance 


* The DB2 XML Extender user-defined functions will now keep small (512KB) 
XML documents in memory while processing them. This reduces 
input/output activity and the contention for the disk that is used for 
temporary files. 


* The definition of the DB2 XML Extender scalar (non-table) user-defined 
functions has been changed so that they can run in parallel. This change 
provides significant performance improvements in the execution of queries 
that refer to the user-defined functions more than once. You must run the 
migration script program to get the parallel capability for the scalar UDFs. 
If you already have columns enabled using the scalar UDFs, you must 
disable all your columns, run the migration script and then re-enable the 
columns. 


Calling XML Extender composition stored procedures 


You can now use XML Extender in different operating systems from a single 
client application, if you write the stored procedure names in uppercase. To 
call the stored procedures in this way, use the result_colname and valid_colname 
versions of the composition stored procedures. Using this method gives you 
the following benefits: 
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* You can use these stored procedures in all DB2 Universal Database 
environments because you can include many columns in the result table. 
The versions of the stored procedures that do not support result_colname 
and valid_colname require exactly one column in the result table. 


* You can use a declared temporary table as your result table. Your 
temporary table is identified by a schema that is set to "session". Declared 
temporary tables enable you to support multi-user client environments. 


It is strongly recommended that you use uppercase when calling the DB2 
XML Extender stored procedures to access the stored procedures consistently 
across platforms. 


Procedure: 


Call the XML Extender using the following syntax: 
CALL DB2XML. function_entry_point 


Where: 


function_entry_point 
Specifies the name of the function. 


In the CALL statement, the arguments that are passed to the stored procedure 
must be host variables, not constants or expressions. The host variables can 
have null indicators. 


See samples for calling stored procedures in the DXXSAMPLES/QCSRC source file, 
In the DXXSAMPLES/QCSRC source directory, SQX code files are provided to call 
XML collection stored procedures using embedded SQL. 


dxxGenXML() 
Purpose: 


Constructs XML documents using data that is stored in the XML collection 
tables that are specified by the <Xcollection> in the DAD file and inserts each 
XML document as a row into the result table. You can also open a cursor on 
the result table and fetch the result set. 


To provide flexibility, dxxGenXML() also lets the user specify the maximum 
number of rows to be generated in the result table. This decreases the amount 
of time the application must wait for the results during any trial process. The 
stored procedure returns the number of actual rows in the table and any error 
information, including error codes and error messages. 
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To support dynamic query, dxxGenXML() takes an input parameter, override. 
Based on the input overrideType, the application can override the SQL_stmt for 
SQL mapping or the conditions in RDB_node for RDB_node mapping in the 
DAD file. The input parameter overrideType is used to clarify the type of the 
override. 


Syntax: 


dxxGenXML (CLOB (100K) DAD, /* input */ 
char(resultTabName) resultTabName, /* input */ 
char(30)  result_column, /* input */ 


char (30) valid_column, /* input */ 
integer overrideType /* input */ 
varchar(1024) override, /* input */ 
integer maxRows , /* input */ 
integer numRows , /* output */ 
long returnCode, /* output */ 


varchar(1024) returnMsg) /* output */ 


Where the varchar_value is 32672 for Windows and UNIX, and 16366 for 
iSeries and z/OS. 


Parameters: 


Table 53. dxxGenXML() parameters 


Parameter Description IN/OUT 
parameter 

DAD A CLOB containing the DAD file. IN 

result TabName The name of the result table, which IN 


should exist before the call. The table 
contains only one column of either 
XMLVARCHAR or XMLCLOB type. 


result_column The name of the column in the result IN 
table in which the composed XML 
documents are stored. 


valid_column The name of the column that indicates |IN 
whether the XML document is valid 
when it is validated against a document 
type definition (DTD). 


overrideType A flag to indicate the type of the IN 

following override parameter: 

* NO_OVERRIDE: No override. 

* SQL_OVERRIDE: Override by an 
SQL_stmt. 


* XML_OVERRIDE: Override by an 
XPath-based condition. 
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Table 53. dxxGenXML/() parameters (continued) 


Parameter Description IN/OUT 
parameter 
override Overrides the condition in the DAD file. | IN 
The input value is based on the 
overrideType. 


* NO_OVERRIDE: A NULL string. 


* SQL_OVERRIDE: A valid SQL 
statement. Using this overrideType 
requires that SQL mapping is used in 
the DAD file. The input SQL 
statement overrides the SQL_stmt in 
the DAD file. 


¢ XML_OVERRIDE: A string that 
contains one or more expressions in 
double quotation marks separated by 
"AND". Using this overrideType 
requires that RDB_node mapping is 
used in the DAD file. 


resultDoc A CLOB that contains the composed OUT 
XML document. 
valid valid is set as follows: OUT 


¢ If VALIDATION=YES then valid=1 
for successful validation or valid=0 
for unsuccessful validation. 

¢ If VALIDATIONE=NO then 
valid=NULL. 


max Rows The maximum number of rows in the IN 
result table. 


numRows The actual number generated rows in OUT 
the result table. 

returnCode The return code from the stored OUT 
procedure. 

returnMsg The message text that is returned in OUT 


case of error. 


Examples: 


The following example fragment assumes that a result table is created with 
the name of XML_ORDER_TAB, and that the table has one column of 
XMLVARCHAR type. A complete, working sample is located in 
DXXSAMPLES/QCSRC (GENX). 
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#include 
#include 


EXEC SQL 
EXEC SQL 
SQL TYPE 


char 
char 
char 
char 
short 
short 
short 
long 
char 
short 
short 
short 
short 
short 
short 
short 
short 
short 
short 
EXEC SQL 


FILE * 
long 


/* creat 


"dxx.h" 
"dxxrc.h" 


INCLUDE SQLCA; 
BEGIN DECLARE SECTION; 
is CLOB(100K) dad; 


result_tab[32]; 
result_colname[32] ; 
valid_colname[32] ; 
override[2]; 
overrideType; 
max_row; 
num_row; 
returnCode; 
returnMsg[1024]; 
dad_ind; 
rtab_ind; 
rcol_ind; 
vcol_ind; 
ovtype_ind; 
ov_ind; 
maxrow_ind; 
numrow_ind; 
returnCode_ind; 
returnMsg_ind; 

END DECLARE SECTION; 


file_handle; 
file_length=0; 


e table */ 


/* 


DAD */ 


name of the result table */ 

name of the result column */ 

name of the valid column, will set to NULL */ 
override, will set to NULL*/ 

defined in dxx.h */ 

maximum number of rows */ 

actual number of rows */ 

return error code */ 

error message text */ 


EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initialize the DAD CLOB object. */ 
dle = fopen( "/dxx/dad/getstart_xcollection.dad", "r" ); 


file_han 
if ( fil 


e handle != NULL ) { 


file_length = fread ((void *) &dad.data; 


9} lee FLL 
if (fi 


E_SIZE, file_handle); 
le_length == 0) { 


printf ("Error reading dad file 
/dxx/dad/getstart_xcollection.dad\n") ; 


rc = 
goto 
} else 
dad. 


else { 


-1; 
exit; 


length = file_length; 


printf("Error opening dad file 


YC = - 
goto e 


} 


1; 
xits 


\n", ); 


/* initialize host variable and indicators */ 
strcpy(result_tab,"xml_order_tab"); 


strcpy(result_colname, "xmlorder") 
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valid_colname = '\0'; 
override[0] = '\0'; 
overrideType = NO_OVERRIDE; 
max_row = 500; 
num_row = 0; 
returnCode = 0; 
msg_txt[0] = '\0'; 
dad_ind = 0; 
rtab_ind = 0; 
rcol_ind = 0; 
vcol_ind = -1; 
ov_ind = -1; 
ovtype_ind = 0; 
maxrow_ind = 0; 
numrow_ind = -1; 
returnCode_ind = -1; 
returnMsg_ind = -1; 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXGENXML" (:dad:dad_ind; 
:result_tab:rtab_ind, 
:result_colname:rcol_ind, 
:valid_colname:vcol_ind, 
:overrideType:ovtype_ind, :override:ov_ind, 
:max_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode: returnCode_ind, 
:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


exit: 
return rc; 


Related tasks: 


* “Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* ‘XML Extenders composition stored procedures” on page 230 
* “How to read syntax diagrams” on page xi 


Related samples: 
* “dxx_xml -- s-getstart_stp_NT-cmd.htm” 
* “dxx_xml -- s-getstart_stp-cmd.htm” 
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dxxRetrieveXML() 
Purpose: 


The stored procedure dxxRetrieveXML() serves as a means for retrieving 
decomposed XML documents. As input, dxxRetrieveXML() takes a buffer 
containing the DAD file, the name of the created result table, and the 
maximum number of rows to be returned. It returns a result set of the result 
table, the actual number of rows in the result set, an error code, and message 
text. 


To support dynamic query, dxxRetrieveXML() takes an input parameter, 
override. Based on the input overrideType, the application can override the 
SQL_stmt for SQL mapping or the conditions in RDB_node for RDB_node 
mapping in the DAD file. The input parameter overrideType is used to clarify 
the type of the override. 


The requirements of the DAD file for dxxRetrieveXML() are the same as the 
requirements for dxxGenXML(). The only difference is that the DAD is not an 
input parameter for dxxRetrieveXML(), but it is the name of an enabled XML 
collection. 


Syntax: 


dxxRetrieveXML(char(collectionName) collectionName, /* input */ 
char(resultTabName) resultTabName, /* input */ 


char (30) result_column, /* input */ 
char (30) valid_column, /* input */ 
integer overridelype, /* input */ 
varchar_value_ override, /* input */ 
integer maxRows , /* input */ 
integer numRows , /* output */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output «/ 


Where varchar_value is 32672 for Windows and UNIX and 16366 for iSeries 
and z/OS. 


Parameters: 


Table 54. dxxRetrieveXML() parameters 


Parameter Description IN/OUT 
parameter 
collectionName The name of an enabled XML IN 
collection. 
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Table 54. dxxRetrieveXML() parameters (continued) 


Parameter 


Description 


IN/OUT 
parameter 


result TabName 


The name of the result table, which 
should exist before the call. The table 
contains only one column of either 
XMLVARCHAR or XMLCLOB type. 


IN 


result_column 


The name of the column in the result 
table in which the composed XML 
documents are stored. 


valid_column 


The name of the column that indicates 
whether the XML document is valid 
when it is validated against a 
document type definition (DTD). 


overrideType 


A flag to indicate the type of the 
following override parameter: 


¢ NO_OVERRIDE: No override. 

¢ SQL_OVERRIDE: Override by an 
SQL_stmt. 

* XML_OVERRIDE: Override by an 
XPath-based condition. 


override 


maxRows 


Overrides the condition in the DAD 
file. The input value is based on the 
overrideType. 


* NO_OVERRIDE: A NULL string. 


« SQL_OVERRIDE: A valid SQL 
statement. Using this overrideType 
requires that SQL mapping is used 
in the DAD file. The input SQL 
statement overrides the SQL_stmt in 
the DAD file. 


* XML_OVERRIDE: A string that 
contains one or more expressions in 
double quotation marks, separated 
by "AND". Using this overrideType 
requires that RDB_node mapping is 
used in the DAD file. 


The maximum number of rows in the 
result table. 


numRows 


The actual number of generated rows 
in the result table. 


returnCode 


The return code from the stored 
procedure. 
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Table 54. dxxRetrieveXML() parameters (continued) 


Parameter Description IN/OUT 
parameter 
returnMsg The message text that is returned in OUT 
case of error. 


Examples: 


The following fragment is an example of a call to dxxRetrieveXML(). In this 
example, a result table is created with the name of XML_ORDER_TAB, and it 
has one column of XMLVARCHAR type. A complete, working sample is 
located in DXXSAMPLES/QCSRC(RTRX). 


#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 
EXEC SQL BEGIN DECLARE SECTION; 
char collectionName[32] ; /* name of an XML collection */ 


char result_tab[32]; /* name of the result table */ 

char result_colname[32] ; /* name of the result column «/ 

char valid_colname[32] ; /* name of the valid column, will set to NULL*/ 
char override[2]; /* override, will set to NULL*/ 

short overrideType; /* defined in dxx.h */ 

short max_row; /* maximum number of rows */ 

short —num_row; /* actual number of rows */ 

long returnCode; /* return error code */ 

char returnMsg[1024] ; /* error message text */ 


short  collectionName_ind; 
short  rtab_ind; 

short  rcol_ind; 

short vcol_ind; 

short  ovtype_ind; 

short ov_ind; 

short maxrow_ind; 

short numrow_ind; 

short returnCode_ind; 
short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 


/* create table */ 
EXEC SQL CREATE TABLE xml_order_tab (xmlorder XMLVarchar) ; 


/* initial host variable and indicators */ 
strcpy(collection, "sales_ord"); 
strcpy(result_tab,"xml_order_tab"); 
strcpy(result_col,"xmlorder") ; 
valid_colname[0] = '\0'; 

override[0] = '\0'; 

overrideType = NO OVERRIDE; 

max_row = 500; 

num_row = 0; 
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returnCode = 0; 
msg_txt[0] '\O'; 
collectionName_ind = 0; 
rtab_ind = 0; 

rcol_ind : 

vcol_ind = -1; 

ov_ind = -1; 

ovtype_ind ; 
maxrow_ind ; 
numrow_ind 1; 
returnCode_ind = -1; 
returnMsg_ind = -1; 


i) 
i) 
d 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXRETRIEVE" 
(:collectionName:collectionName_ind, 
:result_tab:rtab_ind, 
sresult_colname:rcol_ind, 

:valid_colname:vcol_ind, 
:overrideType:ovtype_ind,:override:ov_ind, 
:mMax_row:maxrow_ind, :num_row:numrow_ind, 
:returnCode:returnCode_ind,:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


Related tasks: 


* “Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* “XML Extenders composition stored procedures” on page 230 
* “How to read syntax diagrams” on page xi 


dxxGenXMLClob 


Purpose: 

As input, dxxGenXMLClob takes a buffer containing the DAD. It constructs 
XML documents using data that is stored in the XML collection tables that are 
specified by the <Xcollection> in the DAD and returns the first and typically 
the only XML document generated into the resultDoc CLOB. 


Syntax: 
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dxxGenXMLC1ob(CLOB(100k) DAD /*input*/ 


integer overrideType, /xinput*/ 
varchar(varchar_value) override, /*input/ 

CLOB (1M) resultDoc, /*xoutputx/ 
integer valid, /*xoutput*/ 
integer numDocs, /*output*/ 
long returnCode, /*output*/ 
varchar (1024) returnMsg) , /*xoutput*/ 


Where varchar_value is 32672 for Windows and UNIX and 16366 for iSeries 


and z/OS. 


Parameters: 


Table 55. dxxGenXMLClob parameters 


Parameter 


Description 


IN/OUT 
parameter 


DAD 
overrideType 


A CLOB containing the DAD file. 


A flag to indicate the type of override 
parameter: 


NO_OVERRIDE 
No override. 


SOQL_OVERRIDE 
Override by an SQL_stmt 


XML_OVERRIDE 
Override by an XPath-based 
condition. 


IN 
IN 


override 


Overrides the condition in the DAD file. The 
input value is based on the overrideType. 


NO_OVERRIDE 
A NULL string. 


SQL_OVERRIDE 
A valid SQL statement. Using this 
overrideType requires that SQL 
mapping be used in the DAD file. 
The input SQL statement overrides 
the SQL_stmt in the DAD file. 


XML_OVERRIDE 
A string that contains one or more 
expressions in double quotation 
marks separated by the word and. 
Using this overrideType requires that 
RDB_node mapping be used in the 
DAD file 
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Table 55. dxxGenXMLClob parameters (continued) 


Parameter Description IN/OUT 
parameter 
resultDoc A CLOB that contains the composed XML OUT 
document. 
valid valid is set as follows: OUT 


¢ If VALIDATION=YES then valid=1 for 
successful validation or valid=0 for 
unsuccessful validation. 


¢ If VALIDATION=NO then valid=NULL. 
numDocs The number of XML documents that would |OUT 


be generated from the input data. 
Note: Currently only the first document is 


returned. 
returnCode The return code from the stored procedure. |OUT 
returnMsg The message text that is returned in case of |OUT 
error. 


The CLOB parameter size is 1 MB. If you have CLOB files that are larger than 
1 MB, XML Extender provides a command file to redefine the stored 
procedure parameter. Download the crtgenxc.zip file from the DB2 XML 
Extender Web site. This ZIP file contains the following programs: 


crtgenxc.db2 
For use on XML Extender V7.2 FixPak 5 and later for UNIX and 
Windows. 


crtgenxc.iseries 
For use with XML Extender for iSeries 


For iSeries, place the file as a member into a file. (For example, put the file 
into DXXSAMPLES/SQLSTMT). 


To specify the CLOB length: Open the file in an editor and modify the 
resultDoc parameter, shown in the following example. 


out resultDoc clob(clob_size), 


Size recommendation: The size limit of the resultDoc parameter depends on 
your system setup, but be aware that the amount specified in this parameter 
is the amount allocated by JDBC, regardless of the size of the document. The 
size should accommodate your largest XML files, but should not exceed 1.5 
gigabytes. 


To run the command file on iSeries, from the command line, enter: 
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RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) SRCMBR(CRTGENXC) NAMING (*SQL) 


Where DXXSAMPLES/SQLSTMT matches the Library and File names into 
which you downloaded the file. 


Related tasks: 
“Composing XML documents by using SQL mapping” on page 77 


“Composing XML collections by using RDB_node mapping” on page 81 
“Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* |“XML Extenders composition stored procedures” on page 230 
* |“How to read syntax diagrams” on page xi 


dxxRetrieveXMLClob 
Purpose: 


dxxRetrieveXMLClob enables document composition from relational data. 
This stored procedure also serves as a means for retrieving decomposed XML 
documents. 


The requirements for using dxxRetrieveXMLClob are the same as the 
requirements for dxxGenXMLClob. The only difference is that the DAD is not 
an input parameter for dxxRetrieveXMLClob, but it is the name of an enabled 
XML collection. 


Syntax: 
dxxRetrieveXMLC1ob(CLOB(100k) collelctionName /*input*/ 
integer overrideType, /*input*/ 
varchar_value override, /*input/ 
CLOB(1M) resultDoc, /*xoutput*/ 
integer valid, /*xoutput*/ 
integer numDocs, /*output*/ 
long returnCode, /*xoutput*/ 
varchar (1024) returnMsg) , /*output*/ 


Where varchar_value is 32672 for Windows and UNIX and 16366 for iSeries 
and z/OS. 
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Parameters: 


Table 56. dxxRetrieveXMLClob parameters 


Parameter Description IN/OUT 
parameter 
collectionName The name of an enabled XML IN 
collection. 
overrideType A flag to indicate the type of override IN 
parameter: 


NO_OVERRIDE 
No override. 


SOQL_OVERRIDE 
Override by an SQL_stmt 


XML_OVERRIDE 
Override by an XPath-based 
condition. 


override Overrides the condition in the DAD IN 
file. The input value is based on the 
overrideType. 


NO_OVERRIDE 
A NULL string. 


SQL_OVERRIDE 
A valid SQL statement. Using 
this overrideType requires that 
SQL mapping be used in the 
DAD file. The input SQL 
statement overrides the 
SQL_stmt in the DAD file. 


XML_OVERRIDE 
A string that contains one or 
more expressions in double 
quotation marks separated by 
the word and. Using this 
overrideType requires that 
RDB_node mapping be used 
in the DAD file 


resultDoc The maximum number of rows in the |IN 
result table. 
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Table 56. dxxRetrieveXMLClob parameters (continued) 


Parameter Description IN/OUT 
parameter 
valid valid is set as follows: OUT 


¢ If VALIDATION=YES then valid=1 
for successful validation or valid=0 
for unsuccessful validation. 

¢ If VALIDATION=NO then 
valid=NULL. 


numDocs The number of XML documents that OUT 
would be generated from the input 
data. NOTE: currently only the first 
document is returned. 


returnCode The return code from the stored OUT 
procedure. 
returnMsg The message text that is returned in OUT 


case of error. 


The CLOB parameter size is 1 MB. If you have CLOB files that are larger than 
1 MB, XML Extender provides a command file to redefine the stored 
procedure parameter. Download the crtgenxc.zip file from the DB2 XML 
Extender Web site. This ZIP file contains the following programs: 


crtgenxc.db2 
For use on XML Extender V7.2 Fixpak 5 and later for UNIX and 
Windows. 


crtgenxc.iseries 
For use with XML Extender for iSeries 


For iSeries, place the file as a member into a file. (For example, put the file 
into DXXSAMPLES/SOQLSTMT). 


To specify the CLOB length: Open the file in an editor and modify the 
resultDoc parameter, shown in the following example. 


out resultDoc clob(clob_size), 


Size recommendation: The size limit of the resultDoc parameter depends on 
your system setup, but be aware that the amount specified in this parameter 
is the amount allocated by JDBC, regardless of the size of the document. The 
size should accommodate your largest XML files, but should not exceed 1.5 
gigabytes. 


To run the command file on iSeries, from the command line, enter: 
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RUNSQLSTM SRCFILE(DXXSAMPLES/SQLSTMT) SRCMBR(CRTGENXC) NAMING(*SQL) 


Where DXXSAMPLES/SQLSTMT matches the Library and File names into 
which you downloaded the file. 


Related tasks: 


“Composing XML documents by using SQL mapping” on page 77 


“Composing XML collections by using RDB_node mapping” on page 81 


Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* XML Extenders composition stored procedures” on page 230 
* |‘How to read syntax diagrams” on page xi 


XML Extenders decomposition stored procedures 


The decomposition stored procedures dxxInsertXML() and dxxShredXML() are 
used to break down or shred incoming XML documents and to store data in 
new or existing database tables. The dxxInsertXML() stored procedure takes 
an enabled XML collection name as input. The dxxShredXML() stored 
procedure takes a DAD file as input; it does not require an enabled XML 
collection. 


dxxShredXML() 


Purpose: 


Decomposes XML documents, based on a DAD file mapping, storing the 
content of the XML elements and attributes in specified DB2 tables. In order 
for dxxShredXML() to work, all tables specified in the DAD file must exist, 
and all columns and their data types that are specified in the DAD must be 
consistent with the existing tables. The stored procedure requires that the 
columns specified in the join condition, in the DAD, correspond to primary- 
foreign key relationships in the existing tables. The join condition columns 
that are specified in the RDB_node of the root element_node must exist in the 
tables. 


The stored procedure fragment in this section is a sample for explanation 
purposes. A complete, working sample is located in DXXSAMPLES/QCSRC(SHDX). 


Syntax: 
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dxxShredXML (CLOB (100K) DAD, /* input */ 
CLOB(1M) xmlobj, /* input */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 


Parameters: 


Table 57. dxxShredXML() parameters 


Parameter Description IN/OUT 
parameter 
DAD A CLOB containing the DAD file. IN 
xmlobj An XML document object in XMLCLOB | IN 
type. 
returnCode The return code from the stored OUT 
procedure. 
returnMsg The message text that is returned in OUT 
case of error. 
Examples: 


The following fragment is an example of a call to dxxShredXML(). A 
complete, working sample is located in DXXSAMPLES/QCSRC (SHDX). 


"dxx.h" 
"dxxrc.h" 


#include 
#include 


EXEC SQL 
EXEC SQL 
SQL TYPE 


INCLUDE SQLCA; 


SQL TYPE 


long 
char 
short 
short 
short 
short 


returnCode; 
returnMsg[1024]; 
dad_ind; 
xmlDoc_ind; 
returnCode_ind; 
returnMsg_ind; 


is CLOB(100K) xmlDoc; /* 


BEGIN DECLARE SECTION; 
is CLOB(100K) dad; 


/* DAD */ 
input xml document */ 


/* 
/* 


return error code */ 
error message text */ 


EXEC SQL END DECLARE SECTION; 


FILE 
long 


*file_handle; 
file_length=0; 


/* initialize the DAD CLOB 
file_handle = 
if ( file_handle != NULL ) 


object. */ 


{ 


file_length = fread ((void *) &dad.data; 
, 1, FILE_SIZE, file_handle); 


if (file_length == 0) { 


fopen( "/dxxsamples/dad/getstart_xcollection.dad", "r" ); 


printf ("Error reading dad file getstart_xcollection.dad\n"); 
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re = -l; 
goto exit; 
} else 
dad.length = file_length; 


else { 
printf("Error opening dad file \n"); 
re = -l; 
goto exit; 


} 


/* Initialize the XML CLOB object. */ 
file_handle = fopen( "/dxxsamples/xml/getstart_xcollection.xml", "r" ); 
if ( file_handle != NULL ) { 
file_length = fread ((void *) &xmlDoc.data; 
» 1, FILE_SIZE, 
file_handle); 
if (file_length == 0) { 
printf ("Error reading xml file getstart_xcollection.xml \n"); 
re = -l; 
goto exit; 
} else 
xmlDoc.length = file_length; 
} 


else { 
printf("Error opening xml file \n"); 
re = -l; 
goto exit; 


} 


/* initialize host variable and indicators */ 
returnCode = 0; 
msg_txt [0] ‘'\O'; 
dad_ind = 0; 
xm1Doc_ind = 0; 
returnCode_ind = -1; 
returnMsg_ind = -1; 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXSHRED" (:dad:dad_ind; 
:xm1Doc:xm1Doc_ind, 
sreturnCode:returnCode_ind, 
:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
} 


exit: 
return rc; 


Related tasks: 
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* (“Decomposing an XML collection by using RDB_node mapping” on page 


4 
* /“Decomposing XML documents into DB2 data” on page 11 


ES 
) 


* {Calling XML Extender composition stored procedures” on page 230 


Related reference: 


* |“XML Extenders decomposition stored procedures” on page 245 
* |“How to read syntax diagrams” on page xi 


dxxInsertXML() 
Purpose: 
Takes two input parameters, the name of an enabled XML collection and the 


XML document that are to be decomposed, and returns two output 
parameters, a return code and a return message. 


Syntax: 

dxxInsertXML(char() collectionName, /*input*/ 
CLOB(1M) xmlobj, /* input */ 
long returnCode, /* output */ 
varchar(1024) returnMsg) /* output */ 


Parameters: 


Table 58. dxxinsertXML() parameters 


Parameter Description IN/OUT parameter 
collectionName The name of an enabled XML IN 
collection. 
xmlobj An XML document object in IN 
CLOB type. 
returnCode The return code from the stored |OUT 
procedure. 
returnMsg The message text that is returned |OUT 
in case of error. 


Examples: 


In the following fragment example, the dxxInsertXML() call decomposes the 
input XML document dxx_instal1l/xml/order1.xm] and inserts data into the 
SALES_ORDER collection tables according to the mapping that is specified in 
the DAD file with which it was enabled with. A complete, working sample is 
located in DXXSAMPLES/QCSRC(INSX). 
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#include "dxx.h" 
#include "dxxrc.h" 


EXEC SQL INCLUDE SQLCA; 

EXEC SQL BEGIN DECLARE SECTION; 

char collectionName[32]; /* name of an XML collection */ 
SQL TYPE is CLOB(100K) xmlDoc; /* input xml document */ 
long returnCode; /* return error code */ 
char returnMsg[1024] ; /* error message text */ 
short  collectionName_ind; 

short xmlDoc_ind; 

short returnCode_ind; 

short returnMsg_ind; 

EXEC SQL END DECLARE SECTION; 


FILE *file_handle; 
long file_length=0; 


/* initialize the DAD CLOB object. */ 
file_handle = fopen( "/dxxsamples/dad/getstart_xcollection.dad", "r" ); 
if ( file_handle != NULL ) { 
file_length = fread ((void *) , &dad.data; 
1, FILE_SIZE, file_handle); 
if (file_length == 0) { 
printf ("Error reading dad file getstart_xcollection.dad\n") ; 


re = -l; 
goto exit; 
} else 


dad.length = file_length; 
} 
else { 
printf("Error opening dad file \n"); 
re = -1; 
goto exit; 


} 


/* initialize host variable and indicators */ 
strcpy(collectionName, "sales_ord"); 
returnCode = 0; 

msg_txt[0] = '\0'; 

collectionName_ind = 0; 

xmlDoc_ind = 0; 

returnCode_ind = -1; 

returnMsg_ind = -1; 


/* Call the store procedure */ 

EXEC SQL CALL "DB2XML.DXXINSERTXML" (:collection_name:collection_name_ind, 
:xmlDoc:xmlDoc_ind, 
sreturnCode:returnCode_ind, 
:returnMsg:returnMsg_ind) ; 


if (SQLCODE < 0) { 
EXEC SQL ROLLBACK; 
else 
EXEC SQL COMMIT; 
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} 


exit: 
return rc; 


Related tasks: 


Related reference: 


* |“XML Extenders decomposition stored procedures” on page 245 
* “How to read syntax diagrams” on page xi 
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Chapter 11. XML Extenders administration support tables 


When a database is enabled, a DTD reference table, DTD_REF, and an 
XML_USAGE table are created. The DTD_REF table contains information 
about all of the DTDs. The XML_USAGE table stores common information for 
each XML-enabled column. Each is created with specific PUBLIC privileges. 


DTD reference table 


The XML Extender also serves as an XML DTD repository. When a database is 
XML-enabled, a DTD reference table, DTD_REF, is created. Each row of this 
table represents a DTD with additional metadata information. Users can 
access this table, and insert their own DTDs. The DTDs in the DTD_REF table 
are used to validate XML documents and to help applications to define a 
DAD file. It has the schema name of DB2XML. A DTD_REF table can have the 
columns shown in 


Table 59. DTD_REF table 
Column name Data type Description 


DTDID VARCHAR(128) | The primary key (unique and not NULL). It 
is used to identify the DTD. When it is 
specified in the DAD file, the DAD file must 
follow the schema that is defined by the 


DTD. 
CONTENT XMLCLOB The content of the DTD. 
USAGE _ COUNT INTEGER The number of XML columns and XML 


collections in the database that use the DTD 
to define their DAD files. 


AUTHOR VARCHAR(128) | The author of the DTD, optional “information 
for the user to input. 

CREATOR VARCHAR(128) | The user ID that does the first insertion. The 
CREATOR column is optional. 

UPDATOR VARCHAR(128) | The user ID that does the last update. The 


UPDATOR column is optional. 


Restriction: The DTD can be modified by the application only when the 
USAGE_COUNT is zero. 


Privileges granted to PUBLIC 
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Privileges of INSERT, UPDATE, DELETE, and SELECT are granted for 
PUBLIC. 


XML usage table 
Stores common information for each XML-enabled column. The XML_USAGE 
table’s schema name is DB2XML, and its primary key is (table_name, 
col_name). Only read privileges of this table are granted to PUBLIC. An 
XML_USAGE table is created at the time the database in enabled with the 
columns listed in [Table 60] 


Table 60. XML_USAGE table 


Column name Description 


table_schema For XML column, the schema name of the 
user table that contains an XML column. 
For XML collection, a value of 
"DXX_COLL" as the default schema 
name. 


table_name For XML column, the name of the user 
table that contains an XML column. For 
XML collection, a value 
"DXX_COLLECTION,"” which identifies 
the entity as a collection. 


col_name The name of the XML column or XML 
collection. It is part of the composite key 
along with the table_name. 


DTDID A string associating a DTD inserted into 
DTD_REF with a DTD specified in a 
DAD file; this value must match the 
value of the DTDID element in the DAD. 
This column is a foreign key. 


DAD The content of the DAD file that is 
associated with the column or collection. 


access_mode Specifies which access mode is used: 1 for 
XML collection, 0 for XML column 

default_view Stores the default view name if there is 
one. 

trigger_suffix Not NULL. For unique trigger names. 

validation 1 for yes, 0 for no 


Do not add, modify or delete entries from the XML_USAGE table; it is for 
XML Extender internal use only. 


Privileges granted to PUBLIC 
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For XML_USAGE, the privilege of SELECT is granted for PUBLIC. INSERT, 
DELETE, and UPDATE are granted to DB2XML. 
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Chapter 12. Troubleshooting 


Troubleshooting 


All embedded SQL statements in your program and DB2 command line 
interface (CLI) calls in your program, including those that invoke the DB2 
XML Extender user-defined functions (UDFs), generate codes that indicate 
whether the embedded SQL statement or DB2 CLI call executed successfully. 


Your program can retrieve information that supplements these codes 
including SOLSTATE information and error messages. You can use this 
diagnostic information to isolate and fix problems in your program. 


Occasionally the source of a problem cannot be easily diagnosed. In these 
cases, you might need to provide information to your software support 
provider to isolate and fix the problem. The XML Extender includes a trace 
facility that records the XML Extender activity. The trace information can be 
valuable input to your software service provider. You should use the trace 
facility only under instruction from the software service provider. 


This chapter describes the trace facility, error codes and messages. 


Related reference: 


- FSQLSTATE codes and associated message numbers” on page 259 
. XM Extender messages” on page 263 

- ‘Stopping the trace” on page 256] 

- |’Starting the trace” on page 255] 


Starting the trace 
Purpose: 


Records the XML Extender server activity. To start the trace, apply the on 
option to dxxtre, along with the user profile and the name of an existing 
directory to contain the trace file. When the trace is turned on, the file, 
dxxINSTANCE .trc, is placed in the specified directory. INSTANCE is the 
numeric UID value assigned to the User Profile for which the trace was 
started. The trace file is not limited in size. 


Syntax: 
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Starting the trace from the Qshell: 


»>—dxxtrc—on—user_profile—trace_directory-——@£ >=. 


Starting the trace from the iSeries Navigator: 
call schema.QZXMTRC('on', ‘user_profile', ‘trace_directory'); 


Starting the trace from the OS command line: 
call QDBXM/QZXMTRC PARM(on user_profile ‘trace_directory') 
Parameters: 


Table 61. Trace parameters 


Parameter Description 


user_profile The name of the user profile associated 
with the job within which the XML 
Extender is running. 


trace_directory Name of an existing path and directory 
where the dxxINSTANCE.trc is placed. 
Required, no default. 


Examples: 


The following examples show starting the trace, with file, dxxdb2inst1l.trc, in 
the /u/user1/dxx/trace directory. 
From the Qshell: 
dxxtre on userl /u/userl1/trace 
From the iSeries Navigator: 
call myschema.QZXMTRC('on', ‘userl', '/u/userl1/trace'); 
From the OS command line: 
call QDBXM/QZXMTRC PARM(on userl '/u/userl1/trace') 


Stopping the 


trace 

Purpose: 

Turns the trace off. Trace information is no longer logged. Because running the 
trace log file size is not limited and can impact performance, it is 
recommended to turn trace off in a production environment. 


Syntax: 


Stopping the trace from the Qshell: 
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p>>—dxxtrc—off—user_profile >< 


Stopping the trace from the iSeries Navigator: 
call schema.QZXMTRC('off', ‘user_profile'); 


Stopping the trace from the OS command line: 
call QDBXM/QZXMTRC PARM(off user_profile) 


Parameters: 


Table 62. Trace parameters 


Parameter Description 


user_profile The name of the user profile associated 
with the job within which the XML 
Extender is running. 


Examples: 


The following examples demonstrate stopping the trace. 
From the Qshell: 
dxxtre off userl 
From the iSeries Navigator: 
call myschema.QZXMTRC('off', ‘userl'); 
From the OS command line: 
call QDBXM/QZXMTRC PARM(off user1) 


XML Extenders UDF return codes 


Embedded SQL statements return codes in the SQLCODE, SQLWARN, and 
SOLSTATE fields of the SQLCA structure. This structure is defined in an 
SQLCA INCLUDE file. (For more information about the SQLCA structure and 
SQLCA INCLUDE file, see the DB2 Application Development Guide.) 


DB2 CLI calls return SQLCODE and SQLSTATE values that you can retrieve 
using the SQLError function. (For more information about retrieving error 
information with the SQLError function, see the CLI Guide and Reference.) 


An SQLCODE value of 0 means that the statement ran successfully (with 
possible warning conditions). A positive SQLCODE value means that the 
statement ran successfully but with a warning. (Embedded SQL statements 
return information about the warning that is associated with 0 or positive 
SQLCODE values in the SQLWARN field.) A negative SQLCODE value means 
that an error occurred. 
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DB2 associates a message with each SQLCODE value. If an XML Extender 
UDF encounters a warning or error condition, it passes associated information 
to DB2 for inclusion in the SQLCODE message. 


Embedded SQL statements and DB2 CLI calls that invoke the DB2 XML 
Extender UDFs might return SQLCODE messages and SQLSTATE values that 
are unique to these UDFs, but DB2 returns these values in the same way as it 
does for other embedded SQL statements or other DB2 CLI calls. Thus, the 
way you access these values is the same as for embedded SQL statements or 
DB2 CLI calls that do not start the DB2 XML Extender UDFs. 


XML Extenders stored procedure return codes 


The XML Extender provides return codes to help resolve problems with 
stored procedures. When you receive a return code from a stored procedure, 
check the following file, which matches the return code with an XML 
Extender error message number and the symbolic constant. 


dxx_instal]l/include/dxxrc.h 


Related reference: 


* I“SQLSTATE codes and associated message numbers” on page 258 


SQLSTATE codes and associated message numbers 


Table 63. SQLSTATE codes and associated message numbers 


SOLSTATE Message No. Description 
00000 DxXXnannl No error has occurred. 
01HX0 DXXD003W The element or attribute specified 


in the path expression is missing 
from the XML document. 


38X00 DXXCOO00E The XML Extender is unable to 
open the specified file. 
38X01 DXXA072E XML Extender tried to 


automatically bind the database 
before enabling it, but could not 
find the bind files 


DXXCO001E The XML Extender could not find 
the file specified. 
38X02 DXXC002E The XML Extender is unable to 
read data from the specified file. 
38X03 DXXCO003E The XML Extender is unable to 


write data to the file. 
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Table 63. SQLSTATE codes and associated message numbers (continued) 


SQLSTATE 


Message No. 


Description 


DXXCO11E 


The XML Extender is unable to 
write data to the trace control file. 


38X04 


DXXC004E 


The XML Extender was unable to 
operate the specified locator. 


38X05 


38X06 


DXXCO005E 


DXXCO006E 


The file size is greater than the 
XMLVarchar size and the XML 
Extender is unable to import all 
the data from the file. 


The file size is greater than the 
size of the XMLCLOB and the 
XML Extender is unable to import 
all the data from the file. 


38X07 


DXXC007E 


The number of bytes in the LOB 
Locator does not equal the file 
size. 


38X08 


DXXDO01E 


A scalar extraction function used 
a location path that occurs 
multiple times. A scalar function 
can only use a location path that 
does not have multiple 
occurrence. 


38X09 


38X10 


DXXD002E 


DXXG002E 


The path expression is 
syntactically incorrect. 


The XML Extender was unable to 
allocate memory from the 
operating system. 


38X11 


DXXAO09E 


This stored procedure is for XML 
Column only. 


38X12 


DXXAO10E 


While attempting to enable the 
column, the XML Extender could 
not find the DTD ID, which is the 
identifier specified for the DTD in 
the document access definition 
(DAD) file. 


38X14 


DXXDO00E 


There was an attempt to store an 
invalid document into a table. 
Validation has failed. 


38X15 


DXXA056E 


The validation element in 
document access definition 
(DAD) file is wrong or missing. 
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Table 63. SQLSTATE codes and associated message numbers (continued) 


SQLSTATE 


Message No. 


Description 


DXXA057E 


DXXA058E 


DXXA059E 


DXXA060E 


DXXA061E 


DXXQ000E 


The name attribute of a side table 
in the document access definition 
(DAD) file is wrong or missing. 


The name attribute of a column 
in the document access definition 
(DAD) file is wrong or missing. 


The type attribute of a column in 
the document access definition 
(DAD) file is wrong or missing. 


The path attribute of a column in 
the document access definition 
(DAD) file is wrong or missing. 


The multi_occurrence attribute of 
a column in the document access 
definition (DAD) file is wrong or 
missing. 

A mandatory element is missing 


from the document access 
definition (DAD) file. 


38X16 


DXXG004E 


A null value for a required 
parameter was passed to an XML 
stored procedure. 


38X17 


DXXQO01E 


The SQL statement in the 
document access definition 
(DAD) or the one that overrides it 
is not valid. A SELECT statement 
is required for generating XML 
documents. 


38X18 


DXXGO001E 


DXXG006E 


XML Extender encountered an 
internal error. 


XML Extender encountered an 
internal error while using CLI. 


38X19 


DXXQ002E 


The system is running out of 
space in memory or disk. There is 
no space to contain the resulting 
XML documents. 


38X20 
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DXXQ003W 


The user-defined SQL query 
generates more XML documents 
than the specified maximum. 
Only the specified number of 
documents are returned. 


Table 63. SQLSTATE codes and associated message numbers (continued) 


SQLSTATE 


Message No. 


Description 


38X21 


DXXQ004E 


The specified column is not one 
of the columns in the result of the 
SQL query. 


38X22 


38X23 


DXXQ005E 


DXXQ006E 


The mapping of the SQL query to 
XML is incorrect. 


An attribute_node element in the 
document access definition(DAD) 
file does not have a name 
attribute. 


38X24 


DXXQO007E 


The attribute_node element in the 
document access definition 
(DAD) does not have a column 
element or RDB_node. 


38X25 


DXXQ008E 


A text_node element in the 
document access definition 
(DAD) file does not have a 
column element. 


38X26 


38X27 


DXXQ009E 


DXXQ010E 


DXXQ040E 


DXXQO11E 


DXXQ017E 


DXXQ040E 


The specified result table could 
not be found in the system 
catalog. 


The RDB_node of the 
attribute_node or text_node must 
have a table. 


The RDB_node of the 
attribute_node or text_node must 
have a column. 


An XML document generated by 
the XML Extender is too large to 
fit into the column of the result 
table. 


The specified element name in 
document access definition 
(DAD) file is wrong. 


38X28 


DXXQ012E 


XML Extender could not find the 
expected element while 
processing the DAD. 
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Table 63. SQLSTATE codes and associated message numbers (continued) 


SQLSTATE 


Message No. 


Description 


DXXQ016E 


All tables must be defined in the 
RDB_node of the top element in 
the document access definition 
(DAD) file. Sub-element tables 
must match the tables defined in 
the top element. The table name 
in this RDB_node is not in the top 
element. 


38X29 


DXXQ013E 


DXXQ015E 


The element table or column 
must have a name in the 
document access definition 
(DAD) file. 


The condition in the condition 
element in the document access 
definition (DAD) has an invalid 
format. 


38X30 


DXXQO014E 


DXXQ018E 


An element_node element in the 
document access definition 
(DAD) file does not have a name 
attribute. 


The ORDER BY clause is missing 
from the SQL statement in a 
document access definition 
(DAD) file that maps SQL to 
XML. 


38X31 


DXXQ019E 


The objids element does not have 
a column element in the 
document access definition 
(DAD) file that maps SQL to 
XML. 


38X36 


DXXA073E 


The database was not bound 
when user tried to enable it. 


38X37 


DXXG007E 


The server operating system 
locale is inconsistent with DB2 
code page. 


38X38 


DXXG008E 


The server operating system 
locale can not be found in the 
code page table. 


38X41 


DXXQ048E 


The stylesheet processor returned 
an internal error. The XML 
document or the stylesheet might 
not vaild. 
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Table 63. SQLSTATE codes and associated message numbers (continued) 


SQLSTATE 


Message No. 


Description 


38X42 


DXXQ049E 


The specified output file already 
exists in this directory. 


38X43 


DXXQ050E 


The UDF was unable to create a 
unique file name for the output 
document in the specified 
directory because it does not have 
access, all file names that can be 
generated are in use or directory 
might not exist. 


38X44 


DXXQ051E 


One or more input or output 
parameters have no valid value. 


38x33 


DXXG005E 


This parameter is not supported 
in this release, will be supported 
in the future release. 


38x34 


DXXGO000E 


An invalid file name was 
specified. 


XML Extender messages 


DXXAO000I_ Enabling column <column_name>. 


Please Wait. 
Explanation: This is an informational messages. 


User Response: No action required. 


DXXA001S_ An unexpected error occurred in 
build <build_ID>, file <file_name>, 
and line <line_number>. 


Explanation: An unexpected error occurred. 


User Response: If this error persists, contact 
your Software Service Provider. When reporting 
the error, be sure to include all the message text, 
the trace file, and an explanation of how to 
reproduce the problem. 


DXXA002I 
Explanation: This is an informational message. 


User Response: No action required. 


Connecting to database <database>. 


DXXA003E Cannot connect to database 


<database>. 


Explanation: The database specified might not 
exist or could be corrupted. 


User Response: 


1. Ensure the database is specified correctly. 


2. Ensure the database exists and is accessible. 


3. Determine if the database is corrupted. If it is, 
ask your database administrator to recover it 
from a backup. 


DXXA004E Cannot enable database 


<database>. 


Explanation: The database might already be 
enabled or might be corrupted. 


User Response: 


1. Determine if the database is enabled. 


2. Determine if the database is corrupted. If it is, 
ask your database administrator to recover it 
from a backup. 
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DXXAO005I_—_ Enabling database <database>. 


Please wait. 
Explanation: This is an informational message. 


User Response: No action required. 


DXXAO006I The database <database> was 


enabled successfully. 
Explanation: This is an informational message. 


User Response: No action required. 


DXXA007E Cannot disable database 
<database>. 


Explanation: The database cannot be disabled 
by XML Extender if it contains any XML 
columns or collections. 


User Response: Backup any important data, 
disable any XML columns or collections, and 
update or drop any tables until there are no XML 
data types left in the database. 


DXXA008I_ Disabling column <column_name>. 


Please Wait. 
Explanation: This is an information message. 


User Response: No action required. 


DXXA009E Xcolumn tag is not specified in 
the DAD file. 


Explanation: This stored procedure is for XML 
Column only. 


User Response: Ensure the Xcolumn tag is 
specified correctly in the DAD file. 


DXXA010E Attempt to find DTD ID <dtdid> 
failed. 


Explanation: While attempting to enable the 
column, the XML Extender could not find the 
DTD ID, which is the identifier specified for the 
DTD in the document access definition (DAD) 
file. 


User Response: Ensure the correct value for the 
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DTD ID is specified in the DAD file. 


DXXAOI1E Inserting a record into 
DB2XML.XML_USAGE table 


failed. 


Explanation: While attempting to enable the 
column, the XML Extender could not insert a 
record into the DB2XML.XML_USAGE table. 


User Response: Ensure the 
DB2XML.XML_USAGE table exists and that a 
record by the same name does not already exist 
in the table. 


DXXA012E Attempt to update 
DB2XML.DTD_REF table failed. 


Explanation: While attempting to enable the 
column, the XML Extender could not update the 
DB2XML.DTD_REF table. 


User Response: Ensure the DB2XML.DTD_REF 
table exists. Determine whether the table is 
corrupted or if the administration user ID has 
the correct authority to update the table. 


DXXA013E Attempt to alter table <table_name> 
failed. 


Explanation: While attempting to enable the 
column, the XML Extender could not alter the 
specified table. 


User Response: Check the privileges required to 
alter the table. 


DXXAOI4E_ The specified root ID column: 
<root_id> is not a single primary 
key of table <table_name>. 


Explanation: The root ID specified is either not 
a key, or it is not a single key of table table_name. 


User Response: Ensure the specified root ID is 
the single primary key of the table. 


DXXA015E The column DXXROOT_ID 
already exists in table 
<table_name>. 


Explanation: The column DXXROOTL_ID exists, 
but was not created by XML Extender. 


User Response: Specify a primary column for 
the root ID option when enabling a column, 
using a different different column name. 


DXXA016E_ The input table <table_name> does 
not exist. 


Explanation: The XML Extender was unable to 
find the specified table in the system catalog. 


User Response: Ensure that the table exists in 
the database, and is specified correctly. 


DXXAO17E_ The input column <column_name> 
does not exist in the specified 
table <table_name>. 


Explanation: The XML Extender was unable to 
find the column in the system catalog. 


User Response: Ensure the column exists in a 
user table. 


DXXA018E__ The specified column is not 
enabled for XML data. 


Explanation: While attempting to disable the 
column, XML Extender could not find the 
column in the DB2XML.XML_USAGE table, 
indicating that the column is not enabled. If the 
column is not XML-enabled, you do not need to 
disable it. 


User Response: No action required. 


DXXAOI19E_ A input parameter required to 
enable the column is null. 


Explanation: A required input parameter for the 
enable_column() stored procedure is null. 


User Response: Check all the input parameters 
for the enable_column() stored procedure. 


DXXA020E Columns cannot be found in the 
table <table_name>. 


Explanation: While attempting to create the 
default view, the XML Extender could not find 
columns in the specified table. 


User Response: Ensure the column and table 
name are specified correctly. 


DXXA021E Cannot create the default view 
<default_view>. 


Explanation: While attempting to enable a 
column, the XML Extender could not create the 
specified view. 


User Response: Ensure that the default view 
name is unique. If a view with the name already 
exists, specify a unique name for the default 
view. 


DXXA022I Column <column_name> enabled. 
Explanation: This is an informational message. 


User Response: No response required. 


DXXA023E Cannot find the DAD file. 


Explanation: While attempting to disable a 
column, the XML Extender was unable to find 
the document access definition (DAD) file. 


User Response: Ensure you specified the correct 
database name, table name, or column name. 


DXXA024E The XML Extender encountered 
an internal error while accessing 
the system catalog tables. 


Explanation: The XML Extender was unable to 
access system catalog table. 


User Response: Ensure the database is in a 
stable state. 
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DXXA025E Cannot drop the default view 
<default_view>. 


Explanation: While attempting to disable a 
column, the XML Extender could not drop the 
default view. 


User Response: Ensure the administration user 
ID for XML Extender has the privileges necessary 
to drop the default view. 


DXXA026E Unable to drop the side table 
<side_table>. 


Explanation: While attempting to disable a 
column, the XML Extender was unable to drop 
the specified table. 


User Response: Ensure that the administrator 
user ID for XML Extender has the privileges 
necessary to drop the table. 


DXXA027E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 


° The system is out of memory. 

* A trigger with this name does not exist. 

User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA028E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 

* The system is out of memory. 


* A trigger with this name does not exist. 
User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 
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DXXA029E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 


* The system is out of memory. 

¢ A trigger with this name does not exist. 

User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA030E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 


¢ The system is out of memory. 

¢ A trigger with this name does not exist. 

User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA031E Unable to reset the DXXROOT_ID 
column value in the application 
table to NULL. 


Explanation: While attempting to disable a 
column, the XML Extender was unable to set the 
value of DXXROOT_ID in the application table 
to NULL. 


User Response: Ensure that the administrator 
user ID for XML Extender has the privileges 
necessary to alter the application table. 


DXXA032E Decrement of USAGE_COUNT in 
DB2XML.XML_USAGE table 
failed. 


Explanation: While attempting to disable the 
column, the XML Extender was unable to reduce 
the value of the USAGE_COUNT column by one. 


User Response: Ensure that the 
DB2XML.XML_USAGE table exists and that the 
administrator user ID for XML Extender has the 
necessary privileges to update the table. 


DXXA033E Attempt to delete a row from the 
DB2XML.XML_USAGE table 
failed. 


Explanation: While attempting to disable a 
column, the XML Extender was unable to delete 
its associate row in the DB2XML.XML_USAGE 
table. 


User Response: Ensure that the 
DB2XML.XML_USAGE table exists and that the 
administration user ID for XML Extender has the 
privileges necessary to update this table. 


DXXA034I XML Extender has successfully 


disabled column <column_name>. 
Explanation: This is an informational message 


User Response: No action required. 


DXXA035I XML Extender is disabling 


database <database>. Please wait. 
Explanation: This is an informational message. 


User Response: No action is required. 


DXXA036I XML Extender has successfully 


disabled database <database>. 
Explanation: This is an informational message. 


User Response: No action is required. 


DXXA037E_ The specified table space name is 
longer than 18 characters. 


Explanation: The table space name cannot be 
longer than 18 alphanumeric characters. 


User Response: Specify a name less than 18 
characters. 


DXXA038E_ The specified default view name 
is longer than 18 characters. 


Explanation: The default view name cannot be 
longer than 18 alphanumeric characters. 


User Response: Specify a name less than 18 
characters. 


DXXA039E_ The specified ROOT_ID name is 
longer than 18 characters. 


Explanation: The ROOT_ID name cannot be 
longer than 18 alphanumeric characters. 


User Response: Specify a name less than 18 
characters. 


DXXA046E Unable to create the side table 
<side_table>. 


Explanation: While attempting to enable a 
column, the XML Extender was unable to create 
the specified side table. 


User Response: Ensure that the administrator 
user ID for XML Extender has the privileges 
necessary to create the side table. 


DXXA047E Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 

¢ The DAD file has incorrect syntax. 

¢ The system is out of memory. 

¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA048E Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 


¢ The DAD file has incorrect syntax. 

¢ The system is out of memory. 

¢ Another trigger exists with the same name. 
User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 
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DXXA049E_ Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 

* The DAD file has incorrect syntax. 

¢ The system is out of memory. 

¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA050E Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 

* The DAD file has incorrect syntax. 

¢ The system is out of memory. 

¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA051E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 


¢ The system is out of memory. 

¢ A trigger with this name does not exist. 

User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 


problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA052E Could not disable the column. 


Explanation: XML Extender could not disable a 
column because an internal trigger failed. 
Possible causes: 


¢ The DAD file has incorrect syntax. 
* The system is out of memory. 
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¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA053E Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 

¢ The DAD file has incorrect syntax. 

* The system is out of memory. 

¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA054E Could not enable the column. 


Explanation: XML Extender could not enable a 
column because an internal trigger failed. 
Possible causes: 

¢ The DAD file has incorrect syntax. 

¢ The system is out of memory. 

¢ Another trigger exists with the same name. 


User Response: Use the trace facility to create a 
trace file and try to correct the problem. If the 
problem persists, contact your Software Service 
Provider and provide the trace file. 


DXXA056E_‘ The validation value 
<validation_value> in the DAD file 
is invalid. 


Explanation: The validation element in 
document access definition (DAD) file is wrong 
or missing. 


User Response: Ensure that the validation 
element is specified correctly in the DAD file. 


DXXA057E_ A side table name 
<side_table_name> in DAD is 
invalid. 


Explanation: The name attribute of a side table 
in the document access definition (DAD) file is 
wrong or missing. 


User Response: Ensure that the name attribute 
of a side table is specified correctly in the DAD 
file. 


DXXA058E A column name <column_name> in 
the DAD file is invalid. 


Explanation: The name attribute of a column in 
the document access definition (DAD) file is 
wrong or missing. 


User Response: Ensure that the name attribute 
of a column is specified correctly in the DAD 
file. 


DXXA059E_ The type <column_type> of column 
<column_name> in the DAD file is 
invalid. 


Explanation: The type attribute of a column in 
the document access definition (DAD) file is 
wrong or missing. 


User Response: Ensure that the type attribute of 
a column is specified correctly in the DAD file. 


DXXA060E_ The path attribute </ocation_path> 
of <column_name> in the DAD file 
is invalid. 


Explanation: The path attribute of a column in 
the document access definition (DAD) file is 
wrong or missing. 


User Response: Ensure that the path attribute 
of a column is specified correctly in the DAD 
file. 


DXXAO061E The multi_occurrence attribute 
<multi_occurrence> of 
<column_name> in the DAD file is 
invalid. 


Explanation: The multi_occurrence attribute of a 
column in the document access definition (DAD) 
file is wrong or missing. 


User Response: Ensure that the 
multi_occurrence attribute of a column is 
specified correctly in the DAD file. 


DXXA062E Unable to retrieve the column 
number for <column_name> in 
table <table_name>. 


Explanation: XML Extender could not retrieve 
the column number for column_name in table 
table_name from the system catalog. 


User Response: Make sure the application table 
is well defined. 


DXXA063I ‘Enabling collection 


<collection_name>. Please Wait. 
Explanation: This is an information message. 


User Response: No action required. 


DXXA064I Disabling collection 


<collection_name>. Please Wait. 
Explanation: This is an information message. 


User Response: No action required. 


DXXA065E Calling stored procedure 
<procedure_name> failed. 


Explanation: Check the shared library db2xml 
and see if the permission is correct. 


User Response: Make sure the client has 
permission to run the stored procedure. 
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DXXA066I XML Extender has successfully 
disabled collection 
<collection_name>. 


Explanation: This is an informational message. 


User Response: No response required. 


DXXA067I_ XML Extender has successfully 
enabled collection 
<collection_name>. 


Explanation: This is an informational message. 


User Response: No response required. 


DXXA068I_ XML Extender has successfully 
turned the trace on. 


Explanation: This is an informational message. 


User Response: No response required. 


DXXA069I_ XML Extender has successfully 
turned the trace off. 


Explanation: This is an informational message. 


User Response: No response required. 


DXXA070W_ The database has already been 
enabled. 


Explanation: The enable database command 
was executed on the enabled database 


User Response: No action is required. 


DXXA071W_ The database has already been 
disabled. 


Explanation: The disable database command 
was executed on the disabled database 


User Response: No action is required. 


DXXA072E XML Extender couldn’t find the 
bind files. Bind the database 
before enabling it. 


Explanation: XML Extender tried to 
automatically bind the database before enabling 
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it, but could not find the bind files 


User Response: Bind the database before 
enabling it. 


DXXA073E_ The database is not bound. Please 
bind the database before enabling 
it. 


Explanation: The database was not bound when 
user tried to enable it. 


User Response: Bind the database before 
enabling it. 


DXXA074E_ Wrong parameter type. The stored 
procedure expects a STRING 
parameter. 


Explanation: The stored procedure expects a 
STRING parameter. 


User Response: Declare the input parameter to 
be STRING type. 


DXXA075E Wrong parameter type. The input 
parameter should be a LONG 


type. 
Explanation: The stored procedure expects the 
input parameter to be a LONG type. 


User Response: Declare the input parameter to 
be a LONG type. 


DXXA076E XML Extender trace instance ID 
invalid. 


Explanation: Cannot start trace with the 
instance ID provided. 


User Response: Ensure that the instance ID is a 
valid iSeries user ID. 


DXXA077E The license key is not valid. See 
the server error log for more 
detail. 


Explanation: The software license has expired 
or does not exist. 


User Response: Contact your service provider 


to obtain a new software license. 


DXXCOO0E Unable to open the specified file. 


Explanation: The XML Extender is unable to 
open the specified file. 


User Response: Ensure that the application user 
ID has read and write permission for the file. 


DXXCO001E ‘The specified file is not found. 


Explanation: The XML Extender could not find 
the file specified. 


User Response: Ensure that the file exists and 
the path is specified correctly. 


DXXC002E_ Unable to read file. 


Explanation: The XML Extender is unable to 
read data from the specified file. 


User Response: Ensure that the application user 
ID has read permission for the file. 


DXXC003E Unable to write to the specified 
file. 


Explanation: The XML Extender is unable to 
write data to the file. 


User Response: Ensure that the application user 
ID has write permission for the file or that the 
file system has sufficient space. 


DXXC004E_ Unable to operate the LOB 
Locator: rc=<locator_rc>. 


Explanation: The XML Extender was unable to 
operate the specified locator. 


User Response: Ensure the LOB Locator is set 
correctly. 


DXXCO05E Input file size is greater than 
XMLVarchar size. 


Explanation: The file size is greater than the 
XMLVarchar size and the XML Extender is 
unable to import all the data from the file. 


User Response: Use the XMLCLOB column 
type. 


DXXCO06E The input file exceeds the DB2 
LOB limit. 


Explanation: The file size is greater than the 
size of the XMLCLOB and the XML Extender is 
unable to import all the data from the file. 


User Response: Decompose the file into smaller 
objects or use an XML collection. 


DXXCO007E Unable to retrieve data from the 
file to the LOB Locator. 


Explanation: The number of bytes in the LOB 
Locator does not equal the file size. 


User Response: Ensure the LOB Locator is set 
correctly. 


DXXCO008E Can not remove the file 
<file_name>. 


Explanation: The file has a sharing access 
violation or is still open. 


User Response: Close the file or stop any 
processes that are holding the file. You might 
have to stop and restart DB2. 


DXXCO009E_ Unable to create file to <directory> 
directory. 


Explanation: The XML Extender is unable to 
create a file in directory directory. 


User Response: Ensure that the directory exists, 
that the application user ID has write permission 
for the directory, and that the file system has 
sufficient space for the file. 


DXXCO010E Error while writing to file 
<file_name>. 


Explanation: There was an error while writing 
to the file file_name. 


User Response: Ensure that the file system has 
sufficient space for the file. 
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DXXCO11E Unable to write to the trace 
control file. 


Explanation: The XML Extender is unable to 
write data to the trace control file. 


User Response: Ensure that the application user 
ID has write permission for the file or that the 
file system has sufficient space. 


DXXC012E Cannot create temporary file. 


Explanation: Cannot create file in system temp 
directory. 


User Response: Ensure that the application user 
ID has write permission for the file system temp 
directory or that the file system has sufficient 
space for the file. 


DXXC013E_ ‘The results of the extract UDF 
exceed the size limit for the UDF 
return type. 


Explanation: The data returned by an extract 
UDF must fit into the size limit of the return 
type of the UDF, as defined in the DB2 XML 
Extenders Administration and Programming 
guide. For example, the results of extractVarchar 
must be no more than 4000 bytes (including the 
terminating NULL). 


User Response: Use an extract UDF that has a 
larger size limit for the return type: 254 bytes for 
extractChar(), 4 KB for extractVarchar(), and 2 GB 
for extractClob(). 


DXXDOOOE An invalid XML document is 
rejected. 


Explanation: There was an attempt to store an 
invalid document into a table. Validation has 
failed. 


User Response: Check the document with its 
DTD using an editor that can view invisible 
invalid characters. To suppress this error, turn off 
validation in the DAD file. 
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DXXDO001E = <location_path> occurs multiple 
times. 


Explanation: A scalar extraction function used a 
location path that occurs multiple times. A scalar 
function can only use a location path that does 
not have multiple occurrences. 


User Response: Use a table function (add an ’s’ 
to the end of the scalar function name). 


DXXD002E_ A syntax error occurred near 
position <position> in the search 
path. 


Explanation: The path expression is 
syntactically incorrect. 


User Response: Correct the search path 
argument of the query. Refer to the 
documentation for the syntax of path 
expressions. 


DXXD003W Path not found. Null is returned. 


Explanation: The element or attribute specified 
in the path expression is missing from the XML 
document. 


User Response: Verify that the specified path is 
correct. 


DXXGO000E_ The file name <file_name> is 
invalid. 


Explanation: An invalid file name was 
specified. 


User Response: Specify a correct file name and 
try again. 


DXXGO001E_ An internal error occurred in 
build <build_ID>, file <file_name>, 
and line <line_number>. 


Explanation: XML Extender encountered an 
internal error. 


User Response: Contact your Software Service 
Provider. When reporting the error, be sure to 
include all the messages, the trace file and how 
to reproduce the error. 


DXXG002E_ The system is out of memory. 


Explanation: The XML Extender was unable to 
allocate memory from the operating system. 


User Response: Close some applications and try 
again. If the problem persists, refer to your 
operating system documentation for assistance. 
Some operating systems might require that you 
reboot the system to correct the problem. 


DXXG004E Invalid null parameter. 


Explanation: A null value for a required 
parameter was passed to an XML stored 
procedure. 


User Response: Check all required parameters 
in the argument list for the stored procedure call. 


DXXGO005E Parameter not supported. 


Explanation: This parameter is not supported in 
this release, will be supported in the future 
release. 


User Response: Set this parameter to NULL. 


DXXGO006E Internal Error 
CLISTATE=<clistate>, RC=<cli_rc>, 
build <build_ID>, file <file_name>, 
line <line_number> 
CLIMSG=<CLI_msg>. 


Explanation: XML Extender encountered an 
internal error while using CLI. 


User Response: Contact your Software Service 
Provider. Potentially this error can be caused by 
incorrect user input. When reporting the error, be 
sure to include all output messages, trace log, 
and how to reproduce the problem. Where 
possible, send any DADs, XML documents, and 
table definitions which apply. 


DXXG007E Locale <lJocale> is inconsistent 
with DB2 code page <code_page>. 


Explanation: The server operating system locale 
is inconsistent with DB2 code page. 


User Response: Correct the server operating 


system locale and restart DB2. 


DXXGO008E Locale </ocale> is not supported. 


Explanation: The server operating system locale 
can not be found in the code page table. 


User Response: Correct the server operating 
system locale and restart DB2. 


DXXGO017E_ The limit for 
XML_Extender_constant has been 
exceeded in build build_ID, file 
file_name, and line line_number. 


Explanation: Check the XML Extender 
Administration and Programming Guide to see 
whether your application has exceeded a value 
in the limits table. If no limit has been exceeded, 
contact your Software Service Provider. When 
reporting the error, include all output messages, 
trace files, and information on how to reproduce 
the problem such as input DADs, XML 
documents, and table definitions. 


User Response: Correct the server operating 
system locale and restart DB2. 


DXXM001W A DB2 error occurred. 


Explanation: DB2 encountered the specified 
error. 


User Response: See any accompanying 
messages for futher explanation and refer to DB2 
messages and codes documentation for your 
operating system. 


DXXQO00E <Element> is missing from the 
DAD file. 


Explanation: A mandatory element is missing 
from the document access definition (DAD) file. 


User Response: Add the missing element to the 
DAD file. 


DXXQO001E_ Invalid SQL statement for XML 
generation. 


Explanation: The SQL statement in the 
document access definition (DAD) or the one 
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that overrides it is not valid. A SELECT 
statement is required for generating XML 
documents. 


User Response: Correct the SQL statement. 


DXXQ002E Cannot generate storage space to 
hold XML documents. 


Explanation: The system is running out of space 
in memory or disk. There is no space to contain 
the resulting XML documents. 


User Response: Limit the number of documents 
to be generated. Reduce the size of each 
documents by removing some unnecessary 
element and attribute nodes from the document 
access definition (DAD) file. 


DXXQ003W_ Result exceeds maximum. 


Explanation: The user-defined SQL query 
generates more XML documents than the 
specified maximum. Only the specified number 
of documents are returned. 


User Response: No action is required. If all 
documents are needed, specify zero as the 
maximum number of documents. 


DXXQ004E_ The column <column_name> is not 
in the result of the query. 


Explanation: The specified column is not one of 
the columns in the result of the SOL query. 


User Response: Change the specified column 
name in the document access definition (DAD) 
file to make it one of the columns in the result of 
the SQL query. Alternatively, change the SQL 
query so that it has the specified column in its 
result. 


DXXQO005E Wrong relational mapping. The 
element <element_name> is at a 
lower level than its child column 
<column_name>. 


Explanation: The mapping of the SQL query to 
XML is incorrect. 


User Response: Make sure that the columns in 
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the result of the SQL query are in a top-down 
order of the relational hierarchy. Also make sure 
that there is a single-column candidate key to 
begin each level. If such a key is not available in 
a table, the query should generate one for that 
table using a table expression and the DB2 
built-in function generate_unique(). 


DXXQO06E_ An attribute_node element has no 
name. 


Explanation: An attribute_node element in the 
document access definition (DAD) file does not 
have a name attribute. 


User Response: Ensure that every 
attribute_node has a name in the DAD file. 


DXXQO007E_ The attribute_node 
<attribute_name> has no column 
element or RDB_node. 


Explanation: The attribute_node element in the 
document access definition (DAD) does not have 
a column element or RDB_node. 


User Response: Ensure that every 
attribute_node has a column element or 
RDB_node in the DAD. 


DXXQO08E_ A text_node element has no 
column element. 


Explanation: A text_node element in the 
document access definition (DAD) file does not 
have a column element. 


User Response: Ensure that every text_node has 
a column element in the DAD. 


DXXQO09E_ Result table <table_name> does not 
exist. 


Explanation: The specified result table could 
not be found in the system catalog. 


User Response: Create the result table before 
calling the stored procedure. 


DXXQ010E RDB_node of <node_name> does 
not have a table in the DAD file. 


Explanation: The RDB_node of the 
attribute_node or text_node must have a table. 


User Response: Specify the table of RDB_node 
for attribute_node or text_node in the document 
access definition (DAD) file. 


DXXQ011E RDB_node element of 
<node_name> does not have a 
column in the DAD file. 


Explanation: The RDB_node of the 
attribute_node or text_node must have a column. 


User Response: Specify the column of 
RDB_node for attribute_node or text_node in the 
document access definition (DAD) file. 


DXXQ012E_ Errors occurred in DAD. 


Explanation: XML Extender could not find the 
expected element while processing the DAD. 


User Response: Check that the DAD is a valid 
XML document and contains all the elements 
required by the DAD DTD. Consult the XML 
Extender publication for the DAD DTD. 


DXXQ013E_ The table or column element does 
not have a name in the DAD file. 


Explanation: The element table or column must 
have a name in the document access definition 
(DAD) file. 


User Response: Specify the name of table or 
column element in the DAD. 


DXXQ014E_ An element_node element has no 
name. 


Explanation: An element_node element in the 
document access definition (DAD) file does not 
have a name attribute. 


User Response: Ensure that every element_node 
element has a name in the DAD file. 


DXXQO015E_ ‘The condition format is invalid. 


Explanation: The condition in the condition 
element in the document access definition (DAD) 
has an invalid format. 


User Response: Ensure that the format of the 
condition is valid. 


DXXQO016E_ The table name in this RDB_node 
is not defined in the top element 
of the DAD file. 


Explanation: All tables must be defined in the 
RDB_node of the top element in the document 
access definition (DAD) file. Sub-element tables 
must match the tables defined in the top 
element. The table name in this RDB_node is not 
in the top element. 


User Response: Ensure that the table of the 
RDB node is defined in the top element of the 
DAD file. 


DXXQ017E_ The column in the result table 
<table_name> is too small. 


Explanation: An XML document generated by 
the XML Extender is too large to fit into the 
column of the result table. 


User Response: Drop the result table. Create 
another result table with a bigger column. Rerun 
the stored procedure. 


DXXQ018E The ORDER BY clause is missing 
from the SQL statement. 


Explanation: The ORDER BY clause is missing 
from the SQL statement in a document access 
definition (DAD) file that maps SQL to XML. 


User Response: Edit the DAD file. Add an 
ORDER BY clause that contains the 
entity-identifying columns. 


DXXQ019E_ The element objids has no 
column element in the DAD file. 


Explanation: The objids element does not have 
a column element in the document access 
definition (DAD) file that maps SQL to XML. 
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User Response: Edit the DAD file. Add the key 
columns as sub-elements of the element objids. 


DXXQ020I XML successfully generated. 


Explanation: The requested XML documents 
have been successfully generated from the 
database. 


User Response: No action is required. 


DXXQ021E_ Table <table_name> does not have 
column <column_name>. 


Explanation: The table does not have the 
specified column in the database. 


User Response: Specify another column name 
in DAD or add the specified column into the 
table database. 


DXXQ022E Column <column_name> of 
<table_name> should have type 
<type_name>. 


Explanation: The type of the column is wrong. 


User Response: Correct the type of the column 
in the document access definition (DAD). 


DXXQ023E Column <column_name> of 
<table_name> cannot be longer 
than <length>. 


Explanation: The length defined for the column 
in the DAD is too long. 


User Response: Correct the column length in 
the document access definition (DAD). 


DXXQ024E Can not create table <table_name>. 


Explanation: The specified table can not be 
created. 


User Response: Ensure that the user ID creating 
the table has the necessary authority to create a 
table in the database. 
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DXXQ025I XML decomposed successfully. 


Explanation: An XML document has been 
decomposed and stored in a collection 
successfully. 


User Response: No action is required. 


DXXQ026E XML data <xml_name> is too large 
to fit in column <column_name>. 


Explanation: The specified piece of data from 
an XML document is too large to fit into the 
specified column. 


User Response: Increase the length of the 
column using the ALTER TABLE statement or 
reduce the size of the data by editing the XML 
document. 


DXXQ028E Cannot find the collection 
<collection_name> in the 
XML_USAGE table. 


Explanation: A record for the collection cannot 
be found in the XML_USAGE table. 


User Response: Verify that you have enabled 
the collection. 


DXXQ029E Cannot find the DAD in 
XML_USAGE table for the 
collection <collection_name>. 


Explanation: A DAD record for the collection 
cannot be found in the XML_USAGE table. 


User Response: Ensure that you have enabled 
the collection correctly. 


DXXQ030E Wrong XML override syntax. 


Explanation: The XML_override value is 
specified incorrectly in the stored procedure. 


User Response: Ensure that the syntax of 
XML-_override is correct. 


DXXQ031E Table name cannot be longer than 
maximum length allowed by DB2. 


Explanation: The table name specified by the 
condition element in the DAD is too long. 


User Response: Correct the length of the table 
name in document access definition (DAD). 


DXXQ032E Column name cannot be longer 
than maximum length allowed by 
DB2. 


Explanation: The column name specified by the 
condition element in the DAD is too long. 


User Response: Correct the length of the 
column name in the document access definition 
(DAD). 


DXXQ033E Invalid identifier starting at 
<identifier> 


Explanation: The string is not a valid DB2 SQL 
identifier. 


User Response: Correct the string in the DAD 
to conform to the rules for DB2 SQL identifiers. 


DXXQ034E Invalid condition element in top 
RDB_node of DAD: <condition> 


Explanation: The condition element must be a 
valid WHERE clause consisting of join conditions 
connected by the conjunction AND. 


User Response: See the XML Extender 
documentation for the correct syntax of the join 
condition in a DAD. 


DXXQ035E Invalid join condition in top 
RDB_node of DAD: <condition> 


Explanation: Column names in the condition 
element of the top RDB_node must be qualified 
with the table name if the DAD specifies 
multiple tables. 


User Response: See the XML Extender 
documentation for the correct syntax of the join 
condition in a DAD. 


DXXQ036E A Schema name specified under a 
DAD condition tag is longer than 
allowed. 


Explanation: An error was detected while 
parsing text under a condition tag within the 
DAD. The condition text contains an id qualified 
by a schema name that is too long. 


User Response: Correct the text of the condition 
tags in document access definition (DAD). 


DXXQ037E Cannot generate <element> with 
multiple occurrences. 


Explanation: The element node and its 
descendents have no mapping to database, but 
its multi_occurrence equals YES. 


User Response: Correct the DAD by either 
setting the multi_occurrence to NO or create a 
RDB_node in one of its descendents. 


DXXQ038E The SQL statement is too long: 
SQL_statement 


Explanation: The SQL statement specified in the 
<SQL_stmt> element of DAD exceeds the 
allowed number of bytes. 


User Response: Reduce the length of the SQL 
statement to less than or equal to 32765 bytes for 
Windows and UNIX, or 16380 bytes for OS/390 
and iSeries. 


DXXQ039E Too many columns specified for a 
table in the DAD file. 


Explanation: A DAD file used for 
decomposition or RDB composition can have a 
maximum of 100 text_node and attribute_node 
elements that specify unique columns within the 
same table. 


User Response: Reduce the total number of 
text_node and attribute_node elements that refer 
to unique columns within the same table 100 or 
less. 
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DXXQ040E The element name <element_name> 
in the DAD file is invalid. 


Explanation: The specified element name in the 
document access definition (DAD) file is wrong. 


User Response: Ensure that the element name 
is typed correctly in the DAD file. See the DTD 
for the DAD file. 


DXXQ041W XML document successfully 
generated. One or more override 
paths specified is invalid and 
ignored. 


Explanation: Specify only one override path. 


User Response: Ensure that the element name 
is typed correctly in the DAD file. See the DTD 
for the DAD file. 


DXXQ043E_ Attribute <attr_name> not found 
under element <elem_name>. 


Explanation: The attribute <attr_name> was not 
present in element <elem_name> or one of its 
child elements. 


User Response: Ensure the attribute appears in 
the XML document everywhere that the DAD 
requires it. 


DXXQ044E_ Element <elem_name> does not 
have an ancestor 
element<ancestor>. 


Explanation: According to the DAD, <ancestor> 
is an ancestor element of <elem_name> . In the 
XML document, one or more element 
<elem_name> does not have such an ancestor. 


User Response: Ensure that the nesting of 
elements in the XML document conforms to 
what is specified in the corresponding DAD. 


DXXQ045E_ Subtree under element 
<elem_name> contains multiple 
attributes named<attrib_name>. 


Explanation: A subtree under <elem_name> in 
the XML document contains multiple instances of 
attribute<attrib_name> , which according to the 
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DAD, is to be decomposed into the same row. 
Elements or attributes that are to be decomposed 
must have unique names. 


User Response: Ensure that the element or 
attribute in the subtree has a unique name. 


DXXQ046W The DTD ID was not found in the 
DAD. 


Explanation: In the DAD, VALIDATION is set 
to YES, but the DTDID element is not specified. 
No validation check is performed. 


User Response: No action is required. If 
validation is needed, specify the DTDID element 
in the DAD file. 


DXXQ047E _ Parser error on line <mv> 
linenumber</mv> column 
colnumber: msg 


Explanation: The parser could not parse the 
document because of the reported error. 


User Response: Correct the error in the 
document, consulting the XML specifications if 
necessary. 


DXXQ048E Internal error - see trace file. 


Explanation: The stylesheet processor returned 
an internal error. The XML document or the 
stylesheet might not vaild. 


User Response: Ensure the XML document and 
the stylesheet are valid. 


DXXQ049E_ The output file already exists. 


Explanation: The specified output file already 
exists in this directory. 


User Response: Change the output path or file 
name for the output document to a unique name 
or delete the existing file. 


DXXQO050E_ Unable to create a unique file 
name. 


Explanation: The UDF was unable to create a 
unique file name for the output document in the 


specified directory because it does not have 
access, all file names that can be generated are in 
use or directory might not exist. 


User Response: Ensure that the UDF has access 
to the specified directory, change to a directory 
with available file names. 


DXXQ051E_ No input or output data. 


Explanation: One or more input or output 
parameters have no valid value. 


User Response: Check the statement to see if 
required parameters are missing. 


DXXQ052E_ An error occurred while accessing 
the DB2XML.XML_USAGE table. 


Explanation: Either the database has not been 
enabled or the table DB2XML.XML_USAGE has 
been dropped. 


User Response: Ensure that the database has 
been enabled and the table 
DB2XML.XML_USAGE is accessible. 


DXXQ053E An SQL statement failed : msg 


Explanation: An SQL statement generated 
during XML Extender processing failed to 
execute. DB2XML.XML_USAGE has been 
dropped. 


User Response: Examine the trace for more 
details. If you cannot correct the error condition, 
contact your softwaresService provider. When 
reporting the error, be sure to include all the 
messages, the trace file and how to reproduce the 
error. 


DXXQ054E Invalid input parameter: param 


Explanation: The specified input parameter to a 
stored procedure or UDF is invalid. 


User Response: Check the signature of the 
relevant stored procedure or UDF, and ensure the 
actual input parameter is correct. 
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Appendix A. Samples 


This appendix shows the sample objects that are used with examples in this 
book. 


“DAD file: XML - RDB_node mapping” on page 285 


XML DTD 
The following DTD is used for the getstart.xml document that is referenced 
throughout this book and shown in|Figure 16 on page 282) 
<!xml_ encoding="US-ASCII"?> 


<!ELEMENT Order (Customer, Part+)> 
<!ATTLIST Order key CDATA #REQUIRED> 
<!ELEMENT Customer (Name, Email)> 
<!ELEMENT Name (#PCDATA)> 

<!ELEMENT Email (#PCDATA)> 

<!ELEMENT Part (key, Quantity, ExtendedPrice, Tax, Shipment+)> 
<!ELEMENT key (#PCDATA)> 

<!ELEMENT Quantity (#PCDATA)> 

<!ELEMENT ExtendedPrice (#PCDATA)> 
<!ELEMENT Tax (#PCDATA)> 

<!ATTLIST Part color CDATA #REQUIRED> 
<!ELEMENT Shipment (ShipDate, ShipMode)> 
<!ELEMENT ShipDate (#PCDATA)> 

<!ELEMENT ShipMode (#PCDATA)> 


Figure 15. Sample XML DTD: getstart.dtd 


XML document: getstart.xml 


The following XML document, getstart.xml, is the sample XML document 
that is used in examples throughout this book. It contains XML tags to form a 
purchase order. 
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<?xml version="1.0"?> 
<!DOCTYPE Order SYSTEM 
"dxxsamples/dtd/getstart.dtd"> 
<Order key="1"> 
<Customer> 
<Name>American Motors</Name> 
<Email>parts@am. com</Emai1> 
</Customer> 
<Part color="black "> 
<key>68</key> 
<Quantity>36</Quantity> 
<ExtendedPrice>34850.16</ExtendedPrice> 
<Tax>6.000000e-02</Tax> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>BOAT </ShipMode> 
</Shipment> 
<Shi pment> 
<Shi pDate>1998-08-19</ShipDate> 
<ShipMode>AIR  </ShipMode> 
</Shipment> 
</Part> 
<Part color="red = "> 
<key>128</key> 
<Quantity>28</Quantity> 
<ExtendedPrice>38000.00</ExtendedPrice> 
<Tax>7 .000000e-02</Tax> 
<Shi pment> 
<Shi pDate>1998-12-30</ShipDate> 
<ShipMode>TRUCK </ShipMode> 
</Shipment> 
</Part> 
</Order> 


Figure 16. Sample XML document: getstart.xml 


Document access definition files 


The following sections contain document access definition (DAD) files that 
map XML data to DB2 relational tables, using either XML column or XML 


collection access modes. 


* “DAD file: XML column” on page 283 


XML collection that uses RDB_node mapping. 
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DAD file: XML column 


This DAD file contains the mapping for an XML column, defining the table, 


side tables, and columns that are to contain the XML data. 


<?xml version="1.0"?> 
<!DOCTYPE Order SYSTEM 
"dxxsamples/dtd/dad.dtd"> 
<DAD> 
<dtdid> 
"dxxsamples/dtd/getstart.dtd"</dtdid> 
<validation>YES</validation> 


<Xcolumn> 
<table name="order_side_tab"> 
<column name="order_key" 
type="integer" 
path="/Order/@key" 
multi_occurrence="NO"/> 
<column name="customer" 
type="varchar (50) " 
path="/Order/Customer/Name" 
mul ti_occurrence="NO"/> 
</table> 
<table name="part_side_tab"> 
<column name="price" 
type="decimal (10,2) " 
path="/Order/Part/ExtendedPrice" 
multi_occurrence="YES"/> 
</table> 
<table name="ship_side_tab"> 
<column name="date" 
type="DATE" 
path="/Order/Part/Shipment/ShipDate" 
multi_occurrence="YES"/> 
</table> 


</Xcolumn> 


</DAD> 


Figure 17. Sample DAD file for an XML column: getstart_xcolumn.dad 


DAD file: XML collection - SQL mapping 


This DAD file contains an SQL statement that specifies the DB2 tables, 
columns, and conditions that are to contain the XML data. 
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<?xml version="1.0"?> 

<!DOCTYPE DAD SYSTEM " 

dxxsamples/dtd/dad.dtd"> 

<DAD> 

<validation>N0</validation> 

<Xcollection> 

<SQL_stmt>SELECT o.order_key, customer_name, customer_email, p.part_key, color, 
quantity, price, tax, ship_id, date, mode from order_tab 0, part_tab p, 
(select db2xml.generate_unique(), 

as ship_id, date, mode, part_key from ship_tab) as 


WHERE o.order_key = 1 and 
p.price > 20000 and 
p.order_key = o.order_key and 
s.part_key = p.part_key 
ORDER BY order_key, part_key, ship_id</SQL_stmt> 
<prolog>?xml version="1.0"?</prolog> 
<doctype>!DOCTYPE Order SYSTEM " 
dxxsamples/dtd/getstart.dtd"</doctype> 


Figure 18. Sample DAD file for an XML collection using SQL mapping: order_sql.dad (Part 1 of 2) 
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<root_node> 
<element_node name="Order"> 
<attribute_node name="key"> 
<column name="order_key"/> 
</attribute_node> 
<element_node name="Customer"> 
<element_node name="Name"> 
<text_node><column name="customer_name"/></text_node> 
</element_node> 
<element_node name="Email"> 
<text_node><column name="customer_email"/></text_node> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="color"> 
<column name="color"/> 
</attribute_node> 
<element_node name="key"> 
<text_node><column name="part_key"/></text_node> 
</element_node> 
<element_node name="Quantity"> 
<text_node><column name="quantity"/></text_node> 
</element_node> 
<element_node name="ExtendedPrice"> 
<text_node><column name="price"/></text_node> 
</element_node> 
<element_node name="Tax"> 
<text_node><column name="tax"/></text_node> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 
<text_node><column name="date"/></text_node> 
</element_node> 
<element_node name="ShipMode"> 
<text_node><column name="mode"/></text_node> 
</element_node> 
</element_node> 
</element_node> 
</element_node> 
</root_node> 
</Xcollection> 
</DAD> 


Figure 18. Sample DAD file for an XML collection using SQL mapping: order_sql.dad (Part 2 of 2) 


DAD file: XML - RDB_node mapping 


This DAD file uses <RDB_node> elements to define the DB2 tables, columns, 
and conditions that are to contain XML data. 


<?xml version="1.0"?> 
<!DOCTYPE DAD SYSTEM "SQLLIB/samples/db2xml/dtd/dad.dtd> 
<DAD> 
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<dtdid>E:\dtd\lineIltem.dtd</dtdid> 

<validation>YES</validation> 

<Xcollection> 

<prolog>?xml version="1.0"?</prolog> 

<doctype>!DOCTYPE Order SYSTEM 

"SQLLIB/samples/db2xm1/dtd/getstart.dtd"</doctype> 

<root_node> 

<element_node name="Order"> 

<RDB_node> 

<table name="order_tab"/> 

<table name="part_tab"/> 

<table name="ship_tab"/> 

<condition>order_tab.order_key=part_tab.order_key AND 
part_tab.part_key=ship_tab.part_key </condition> 

</RDB_node> 

<attribute_node name="Key"> 

<RDB_node> 

<table name="order_tab"/> 

<column name="order_key"/> 

</RDB_node> 

</attribute_node> 

<element_node name="Customer"> 


<element_node name="Name"> 
<text_node> 
<RDB_node> 
<table name="order_tab"/> 
<column name="customer_name"/> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name="Email"> 
<text_node> 
<RDB_node> 
<table name="order_tab"/> 
<column name="customer_email"/> 
</RDB_node> 
</text_node> 
</element_node> 
</element_node> 
<element_node name="Part"> 
<attribute_node name="Key"> 
<RDB_node> 
<table name="part_tab"/> 
<column name="part_key"/> 
</RDB_node> 
</attribute_node> 
<element_node name="ExtendedPrice"> 
<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="price"/> 
<condition>price > 2500.00</condition> 
</RDB_node> 
</text_node> 
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</element_node> 
<element_node name="Tax"> 
<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="tax"/> 
</RDB_node> 
</text_node> 
</element_node> 


<element_node name="Quantity"> 
<text_node> 
<RDB_node> 
<table name="part_tab"/> 
<column name="qty"/> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name="Shipment" multi_occurrence="YES"> 
<element_node name="ShipDate"> 
<text_node> 
<RDB_node> 
<table name="ship_tab"/> 
<column name="date"/> 
<condition>date > '1966-01-01'</condition> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name="ShipMode"> 
<text_node> 
<RDB_node> 
<table name="ship_tab"/> 
<column name="mode"/> 
</RDB_node> 
</text_node> 
</element_node> 
<element_node name="Comment"> 
<text_node> 
<RDB_node> 
<table name="ship_tab"/> 
<column name="comment"/> 
</RDB_node> 
</text_node> 
</element_node> 
</element_node> <!-- end of element Shipment--> 
</element_node> <!-- end of element Part --> 
</element_node> <!-- end of element Order --> 
</root_node> 


</Xcollection> 


</DAD> 


Appendix A. Samples 


287 


288 Administration and Programming for iSeries 


Appendix B. Code page considerations 


XML documents and other related files must be encoded properly for each 

client or server that accesses the files. The XML Extender makes some 

assumptions when processing a file, you need to understand how it handles 

code page conversions. The primary considerations are: 

* Ensuring that the actual code page of the client retrieving an XML 
document from DB2 matches the encoding of the document. 


* Ensuring that, when the document is processed by an XML parser, the 
encoding declaration of the XML document is also consistent with the 
document's actual encoding. 


* Ensuring that the locales are configured properly. 


For iSeries, the job, DB2 and the XML document must all have the same 
CCSID. The following section describes methods for ensuring that the CCSIDs 
are consistent. 


Configuring locale settings 


The XML Extender selects completion and error messages from a message 
catalog based on your locale settings. To receive the messages in your 
language, you must install the XML Extender message catalog, and have the 
locale set up correctly. XML Extender installs the message catalog for your 
language in the IFS directory, /QIBM/ProdData/DB2Extenders/XML/MRIxxxx, 
where xxxx is the language code. 


For example, the message catalog for English, 2924, is installed in the 
directory: /QIBM/ProdData/DB2Extenders/XML/MRI2924/dxx.cat. To have the 
English 2924 message catalog selected by the XML Extender, set up the user 
profile, using the WRKUSRPRF command: 


Language ID .......... LANGID ENU 
Country/Region ID........ CNTRYID US 
Coded character set ID..... CCSID 037 


All instances of the XML Extender running under this user profile will use the 
MRI2924 message catalog. 


Encoding declaration considerations 


The encoding declaration specifies the code page of the XML document’s 
encoding and appears on the XML declaration statement. When using the 
XML Extender, it is important to ensure that the encoding of the document 
matches the job and DB2. 
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Consistent encodings and encoding declarations 
When an XML document is processed or exchanged with another system, it is 
important that the encoding declaration corresponds to the actual encoding of 
the document. Ensuring that the encoding of a document is consistent with 
the client is important because XML tools, like parsers, generate an error for 
an entity that includes an encoding declaration other than that named in the 
declaration. 


The consequences of having different code pages are the following possible 
situations: 


* A conversion in which data is lost might occur. 

* The declared encoding of the XML document might no longer be consistent 
with the actual document encoding, if the document is retrieved by a client 
with a different code page than the declared encoding of the document. 

Declaring an encoding 


The default value of the encoding declaration is UTF-8, and the absence of an 
encoding declaration means the document is in UTF-8. 


To declare an encoding value: 


In the XML document declaration specify the encoding declaration with the 
name of the code page of the client. For example: 


<?xml version="1.0" encoding="UTF-8" ?> 


Preventing inconsistent XML documents 


Use one of the following recommendations for ensuring that the XML 
document encoding is consistent with the client code page, before handing the 
document to an XML processor, such as a parser: 


* When exporting a document from the database using the XML Extender 
UDFs, try one of the following techniques (assuming the XML Extender has 
exported the file, in the server code page, to the file system on the server): 


— Convert the document to the declared encoding code page 
— Override the declared encoding, if the tool has an override facility 


— Manually change the encoding declaration of the exported document to 
the document’s actual encoding (that is, the server code page) 


* When exporting a document from the database using the XML Extender 
stored procedures, try one of the following techniques (assuming the client 
is querying the result table, in which the composed document is stored): 


— Convert the document to the declared encoding code page 


— Override the declared encoding, if the tool has an override facility 
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— Before running the stored procedure, have the client set the CCSID 
variable to force the client code page to a code page that is compatible 
with the encoding declaration of the XML document. 


— Manually change the encoding declaration of the exported document to 
the document’s actual encoding (that is, the client code page) 
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Appendix C. XML Extender limits 


This appendix describes the limits for: 


* XML Extender objects 


* values returned by user-defined functions 


* stored procedures parameters 


* administration support table columns 


* composition and decomposition 


The following table describes the limits for XML Extender objects. 


Table 64. Limits for XML Extender objects 


Object 


Limit 


Maximum number of rows in a table ina 
decomposition XML collection 


10240 rows from each decomposed XML 
document 


Maximum characters in a column name 
specified in a default view 


10 characters 


Maximum bytes in XML File path name 
specified as a parameter value 


512 bytes 


Length of the sql_stmt element in a DAD 
file for SQL composition 


Windows and UNIX 

operating systems: 32,765 bytes 
OS/390 and iSeries operating 
systems: 16,380 bytes 


Maximum number of columns for one 
table, specified for one table in the DAD 
file for RDB_node decomposition 


100 columns (columns for a table 
are specified by text_node 

and attribute_node elements 

in a DAD file. 


The following table describes the limits values returned by XML Extender 


user-defined functions. 


Table 65. Limits for user-defined function value 


User-defined functions returned values 


Limit 


Maximum bytes returned by an 
extractCHAR UDF 


254 bytes 


Maximum bytes returned by an 
extractCLOB UDF 


2 gigabytes 


Maximum bytes returned by an 
extractVARCHAR UDF 


4 kilobytes 
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The following table describes the limits for parameters of XML Extender 


stored procedures. 


Table 66. Limits for stored procedure parameters 


Stored procedure parameters 


Limit 


Maximum size of an XML document 
CLOB! 


1 megabytes 


Maximum size of a Document Access 
Definition (DAD) CLOB! 


100 kilobytes 


Maximum size of collectionName 30 bytes 
Maximum size of colName 30 bytes 
Maximum size of dbName 8 bytes 
Maximum size of default View 128 bytes 
Maximum size of rootID 128 bytes 
Maximum size of resultTabName 18 bytes 
Maximum size of tablespace 8 bytes 
Maximum size of thName* 18 bytes 


Notes: 


1. This size can be changed for dxxGenXMLClob and dxxRetrieveXMLCLOB. 


2. If the value of the thName parameter is qualified by a schema name, the entire 
name (including the separator character) must be no longer than 128 bytes. 


The following table describes the limits for the DB2XML.DTD_REF table. 


Table 67. XML Extender limits 


DB2XML.DTD_REF table columns Limit 

Size of AUTHOR column 128 bytes 
Size of CREATOR column 128 bytes 
Size of UPDATOR column 128 bytes 
Size of DTDID column 128 bytes 


Size of CLOB column 


100 kilobytes 


Names can undergo expansion when DB2 converts them from the client code 
page to the database code page. A name might fit within the size limit at the 
client, but exceed the limit when the stored procedure gets the converted 


name. 
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The following table describes limits for composition and decomposition. 
Table 68. Limits for XML Extender composition and decomposition 
Object Limit 


Maximum number of rows inserted into a 1024 rows from each decomposed XML 
table in a decomposition XML collection document 


Maximum length of the name attribute in 63 bytes 
elements_node or attribute_node within a 
DAD 


Maximum characters in a column name 10 characters 
specified in a default view 


Maximum bytes in XMLFile path name 512 bytes 
specified as a parameter value 
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Notices 


IBM may not offer the products, services, or features discussed in this 
document in all countries. Consult your local IBM representative for 
information on the products and services currently available in your area. Any 
reference to an IBM product, program, or service is not intended to state or 
imply that only that IBM product, program, or service may be used. Any 
functionally equivalent product, program, or service that does not infringe 
any IBM intellectual property right may be used instead. However, it is the 
user’s responsibility to evaluate and verify the operation of any non-IBM 
product, program, or service. 


IBM may have patents or pending patent applications covering subject matter 
described in this document. The furnishing of this document does not give 
you any license to these patents. You can send license inquiries, in writing, to: 


IBM Director of Licensing 
IBM Corporation 

North Castle Drive 
Armonk, NY 10504-1785 
US.A. 


For license inquiries regarding double-byte (DBCS) information, contact the 
IBM Intellectual Property Department in your country/region or send 
inquiries, in writing, to: 


IBM World Trade Asia Corporation 
Licensing 

2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106, Japan 


The following paragraph does not apply to the United Kingdom or any 
other country/region where such provisions are inconsistent with local law: 
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY 
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow 
disclaimer of express or implied warranties in certain transactions, therefore, 
this statement may not apply to you. 


This information could include technical inaccuracies or typographical errors. 


Changes are periodically made to the information herein; these changes will 
be incorporated in new editions of the publication. IBM may make 


© Copyright IBM Corp. 1999, 2003 297 


improvements and/or changes in the product(s) and/or the program(s) 
described in this publication at any time without notice. 


Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any manner serve as an endorsement of those 
Web sites. The materials at those Web sites are not part of the materials for 
this IBM product and use of those Web sites is at your own risk. 


IBM may use or distribute any of the information you supply in any way it 
believes appropriate without incurring any obligation to you. 


Licensees of this program who wish to have information about it for the 
purpose of enabling: (i) the exchange of information between independently 
created programs and other programs (including this one) and (ii) the mutual 
use of the information which has been exchanged, should contact: 


IBM Canada Limited 
Office of the Lab Director 
8200 Warden Avenue 
Markham, Ontario 

L6G 1C7 

CANADA 


Such information may be available, subject to appropriate terms and 
conditions, including in some cases, payment of a fee. 


The licensed program described in this information and all licensed material 
available for it are provided by IBM under terms of the IBM Customer 
Agreement, IBM International Program License Agreement, or any equivalent 
agreement between us. 


Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments 
may vary significantly. Some measurements may have been made on 
development-level systems and there is no guarantee that these measurements 
will be the same on generally available systems. Furthermore, some 
measurements may have been estimated through extrapolation. Actual results 
may vary. Users of this document should verify the applicable data for their 
specific environment. 


Information concerning non-IBM products was obtained from the suppliers of 
those products, their published announcements or other publicly available 
sources. IBM has not tested those products and cannot confirm the accuracy 
of performance, compatibility or any other claims related to non-IBM 
products. Questions on the capabilities of non-IBM products should be 
addressed to the suppliers of those products. 
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All statements regarding IBM’s future direction or intent are subject to change 
or withdrawal without notice, and represent goals and objectives only. 


This information may contain examples of data and reports used in daily 
business operations. To illustrate them as completely as possible, the examples 
include the names of individuals, companies, brands, and products. All of 
these names are fictitious and any similarity to the names and addresses used 
by an actual business enterprise is entirely coincidental. 


COPYRIGHT LICENSE: 


This information may contain sample application programs in source 
language, which illustrates programming techniques on various operating 
platforms. You may copy, modify, and distribute these sample programs in 
any form without payment to IBM, for the purposes of developing, using, 
marketing or distributing application programs conforming to the application 
programming interface for the operating platform for which the sample 
programs are written. These examples have not been thoroughly tested under 
all conditions. IBM, therefore, cannot guarantee or imply reliability, 
serviceability, or function of these programs. 


Each copy or any portion of these sample programs or any derivative work 
must include a copyright notice as follows: 


© (your company name) (year). Portions of this code are derived from IBM 


Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_. All 
rights reserved. 
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Trademarks 


The following terms are trademarks of International Business Machines 
Corporation in the United States, other countries, or both. 


ACF/VTAM IMS/ESA 
AISPO iSeries 
AIX LAN Distance 
AIX/6000 MVS 
AlXwindows MVS/ESA 
AnyNet MVS/XA 
APPN Net.Data 
AS/400 0S/390 
BookManager OS/400 
CICS PowerPC 
C Set++ pSeries 
C/370 QBIC 
DATABASE 2 QMF 
DataHub RACF 
DataJoiner RISC System/6000 
DataPropagator RS/6000 
DataRefresher $/370 
DB2 SP 
DB2 Connect SQL/DS 
DB2 Extenders SQL/400 
DB2 OLAP Server System/370 
DB2 Universal Database System /390 
Distributed Relational SystemView 
Database Architecture VisualAge 
DRDA VM/ESA 
eNetwork VSE/ESA 
eServer VTAM 
Extended Services WebExplorer 
FFST WIN-OS/2 
First Failure Support Technology z/OS 
IBM zSeries 
IMS 


The following terms are trademarks or registered trademarks of other 
companies: 


Microsoft, Windows, and Windows NT are trademarks or registered 
trademarks of Microsoft Corporation. 


Java and all Java-based trademarks and logos, and Solaris are trademarks of 
Sun Microsystems, Inc. in the United States, other countries, or both. 
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Tivoli and NetView are trademarks of Tivoli Systems Inc. in the United States, 
other countries, or both. 


UNIX is a registered trademark in the United States, other countries or both 
and is licensed exclusively through X/Open Company Limited. 


Other company, product, or service names may be trademarks or service 
marks of others. 
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XML Extender glossary 


absolute location path. The full path name of an object. The absolute path name begins at the highest 
level, or "root" element, which is identified by the forward slash (/) or back slash (\) character. 


access and storage method. Associates XML documents to a DB2 database through two major access 
and storage methods: XML columns and XML collections. See also XML column and XML collection. 


access function. A user-provided function that converts the data type of text stored in a column to a 
type that can be processed by Text Extender. 


administration. The task of preparing text documents for searching, maintaining indexes, and getting 
status information. 


administrative support table. One of the tables that are used by a DB2 extender to process user 
requests on image, audio, and video objects. Some administrative support tables identify user tables and 
columns that are enabled for an extender. Other administrative support tables contain attribute 
information about objects in enabled columns. Also called a metadata table. 


administrative support tables. A tables used by a DB2 extender to process user requests on XML 
objects. Some administrative support tables identify user tables and columns that are enabled for an 
extender. Other administrative support tables contain attribute information about objects in enabled 
columns. Synonymous with metadata table. 


analyze. To calculate numeric values for the features of an image and add the values to a QBIC catalog. 
API. See application programming interface. 


application programming interface (API). 


(1) A functional interface supplied by the operating system or by a separately orderable licensed 
program. An API allows an application program that is written in a high-level language to use 
specific data or functions of the operating system or the licensed programs. 


(2) In DB2, a function within the interface, for example, the get error message API. 


(3) The DB2 extenders provide APIs for requesting user-defined functions, administrative operations, 
display operations, and video scene change detection. The DB2 text extender provides APIs for 
requesting user-defined functions, administrative operations, and information retrieval services.In 
DB2, a function within the interface. For example, the get error message API. 


attribute. See XML attribute. 
attribute_node. A representation of an attribute of an element. 


binary large object (BLOB). A binary string whose length can be up to 2 GB. Image, audio, and video 
objects are stored in a DB2 database as BLOBs. 


Boolean search. A search in which one or more search terms are combined using Boolean operators. 


bound search. A search in Korean documents that respects word boundaries. 
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browse. To view text displayed on a computer monitor. 


browser. A Text Extender function that enables you to display text on a computer monitor.See Web 
browser. 


B-tree indexing. The native index scheme provided by the DB2 engine. It builds index entries in the 
B-tree structure. Supports DB2 base data types. 


cast function. A function that is used to convert instances of a (source) data type into instances of a 
different (target) data type. In general, a cast function has the name of the target data type. It has one 
single argument whose type is the source data type; its return type is the target data type. 


catalog view. A view of a system table created by Text Extender for administration purposes. A catalog 
view contains information about the tables and columns that have been enabled for use by Text 
Extender. 


CCSID. Coded Character Set Identifier. 

character large object (CLOB). A character string of single-byte characters, where the string can be up 
to 2 GB. CLOBs have an associated code page. Text objects that contain single-byte characters are stored 
in a DB2 database as CLOBs. 

CLOB. Character large object. 


code page. An assignment of graphic characters and control function meanings to all code points. For 
example, assignment of characters and meanings to 256 code points for an 8-bit code. 


column data. The data stored inside of a DB2 column. The type of data can be any data type supported 
by DB2. 


command line processor. A program called DB2TX that: 
Allows you to enter Text Extender commands 
Processes the commands 


Displays the result. 
compose. To generate XML documents from relational data in an XML collection. 


condition. A specification of either the criteria for selecting XML data or the way to join the XML 
collection tables. 


DAD. See Document access definition. 


data interchange. The sharing of data between applications. XML supports data interchange without 
needing to go through the process of first transforming data from a proprietary format. 


data source. A local or remote relational or nonrelational data manager that is capable of supporting 
data access via an ODBC driver that supports the ODBC APIs. 


data stream. Information returned by an API function, comprising text (at least one paragraph) 
containing the term searched for, and information for highlighting the found term in that text. 


data type. An attribute of columns and literals. 
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database partition. A part of the database that consists of its own user data, indexes, configuration 
files, and transaction logs. Sometimes called a node or database node. 


database partition server. Manages a database partition. A database partition server is composed of a 
database manager and the collection of data and system resources that it manages. Typically, one 
database partition server is assigned to each machine. 


DBCLOB. Double-byte character large object. 

DBCS. Double-byte character support. 

decompose. Separates XML documents into a collection of relational tables in an XML collection. 
default casting function. Casts the SQL base type to a UDT. 


default view. A representation of data in which an XML table and all of its related side tables are 
joined. 

disable. To restore a database, a text table, or a text column, to its condition before it was enabled for 
XML Extender by removing the items created during the enabling process. 

distinct type. See user-defined type. 


document. See text document. 


Document Access Definition (DAD). Used to define the indexing scheme for an XML column or 
mapping scheme of an XML collection. It can be used to enable an XML Extender column of an XML 
collection, which is XML formatted. 


Document type definition (DTD). A set of declarations for XML elements and attributes. The DTD 
defines what elements are used in the XML document, in what order they can be used, and which 
elements can contain other elements. You can associate a DTD with a document access definition (DAD) 
file to validate XML documents. 


double-byte character large object (DBCLOB). A character string of double-byte characters, or a 
combination of single-byte and double-byte characters, where the string can be up to 2 GB. DBCLOBs 
have an associated code page. Text objects that include double-byte characters are stored in a DB2 
database as DBCLOBs. 


DTD. (1). (2) See Document type definition. 


DTD reference table (DTD_REF table). A table that contains DTDs, which are used to validate XML 
documents and to help applications to define a DAD. Users can insert their own DTDs into the 
DTD_REF table. This table is created when a database is enabled for XML. 


DTD_REF table. DTD reference table. 


DTD repository. A DB2 table, called DTD_REF, where each row of the table represents a DID with 
additional metadata information. 


EDI. Electronic Data Interchange. 
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Electronic Data Interchange (EDI). A standard for electronic data interchange for business-to-business 
(B2B) applications. 


element. See XML element. 


element_node. A representation of an element. An element_node can be the root element or a child 
element. 


embedded SQL. SQL statements coded within an application program. See static SQL. 
enable. To prepare a database, a text table, or a text column, for use by XML Extender. 


escape character. A character indicating that the subsequent character is not to be interpreted as a 
masking character. 


expand. The action of adding to a search term additional terms derived from a thesaurus. 


Extensible Stylesheet language (XSL). A language used to express stylesheets. XSL consists of two 
parts: a language for transforming XML documents, and an XML vocabulary for specifying formatting 
semantics. 


Extensible Stylesheet Language Transformation (XSLT). A language used to transform XML 
documents into other XML documents. XSLT is designed for use as part of XSL, which is a stylesheet 
language for XML. 


external file. A text document in the form of a file stored in the operating system’s file system, rather 
than in the form of a cell in a table under the control of DB2. A file that exists in a file system external to 
DB2. 


file reference variable. A programming variable that is useful for moving a LOB to and from a file on 
a client workstation. 


foreign key. A key that is part of the definition of a referential constraint and that consists of one or 
more columns of a dependent table. 


function. See access function. 
gigabyte (GB). One billion (109) bytes. When referring to memory capacity, 1 073 741 824 bytes. 


host variable. A variable in an application program that can be referred to in embedded SQL 
statements. Host variables are the primary mechanism for transmitting data between a database and 
application program work areas. 


image. An electronic representation of a picture. 


index. To extract significant terms from text, and store them in a text index.A set of pointers that are 
logically ordered by the values of a key. Indexes provide quick access to data and can enforce 
uniqueness on the rows in the table. 


Java Database Connectivity (JDBC). An application programming interface (API) that has the same 
characteristics as Open Database Connectivity (ODBC) but is specifically designed for use by Java 
database applications. Also, for databases that do not have a JDBC driver, JDBC includes a JDBC to 
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ODBC bridge, which is a mechanism for converting JDBC to ODBC; JDBC presents the JDBC API to Java 
database applications and converts this to ODBC. JDBC was developed by Sun Microsystems, Inc. and 
various partners and vendors. 


JDBC. Java Database Connectivity. 


join. A relational operation that allows for retrieval of data from two or more tables based on matching 
column values. 


joined view. A DB2 view created by the "CREATE VIEW" statement which join one more tables 
together. 


kilobyte (KB). One thousand (103) bytes. When referring to memory capacity, 1024 bytes. 


large object (LOB). A sequence of bytes, where the length can be up to 2 GB. A LOB can be of three 
types: binary large object (BLOB), character large object (CLOB), or double-byte character large object 
(DBCLOB). 


linguistic index. A text index containing terms that have been reduced to their base form by linguistic 
processing. “Mice”, for example, would be indexed as “mouse”. See also precise index, Ngram index, and 
dual index. 


LOB. Large object. 


LOB locator. A small (4-byte) value stored in a host variable that can be used in a program to refer to a 
much larger LOB in a DB2 database. Using a LOB locator, a user can manipulate the LOB as if it was 
stored in a regular host variable, and without the need to transport the LOB between the application on 
the client machine and the database server. 


local file system. A file system that exists in DB2 


location path. Location path is a sequence of XML tags that identify an XML element or attribute. The 
location path identifies the structure of the XML document, indicating the context for the element or 
attribute. A single slash (/) path indicates that the context is the whole document. The location path is 
used in the extracting UDFs to identify the elements and attributes to be extracted. The location path is 
also used in the DAD file to specify the mapping between an XML element, or attribute, and a DB2 
column when defining the indexing scheme for XML column. Additionally, the location path is used by 
the Text Extender for structural-text search. 


locator. A pointer which can be used to locate an object. In DB2, the large object block (LOB) locator is 
the data type which locates LOBs. 


mapping scheme. A definition of how XML data is represented in a relational database. The mapping 
scheme is specified in the DAD. The XML Extender provides two types of mapping schemes: SQL 
mapping and relational database node (RDB_node) mapping. 


megabyte (MB). One million (10°) bytes. When referring to memory capacity, 1 048 576 bytes. 
metadata table. See administrative support table. 


multiple occurrence. An indication of whether a column element or attribute can be used more than 
once in a document. Multiple occurrence is specified in the DAD. 
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object. In object-oriented programming, an abstraction consisting of data and the operations associated 
with that data. 


ODBC. Open Database Connectivity. 


Open Database Connectivity. A standard application programming interface (API) for accessing data in 
both relational and nonrelational database management systems. Using this API, database applications 
can access data stored in database management systems on a variety of computers even if each database 
management system uses a different data storage format and programming interface. ODBC is based on 
the call level interface (CLI) specification of the X/Open SQL Access Group and was developed by 
Digital Equipment Corporation (DEC), Lotus, Microsoft, and Sybase. Contrast with Java Database 
Connectivity. 


overloaded function. A function name for which multiple function instances exist. 
path expression. See location path. 
predicate. An element of a search condition that expresses or implies a comparison operation. 


primary key. A unique key that is part of the definition of a table. A primary key is the default parent 
key of a referential constraint definition. 


procedure. See stored procedure. 
QBIC catalog. A repository that holds data about the visual features of images. 


query object. An object that specifies the features, feature, values, and feature weights for a QBIC 
query. The object can be named and saved for subsequent use in a QBIC query. Contrast with query 
string 


RDB_node. Relational database node. 


RDB_node mapping. The location of the content of an XML element, or the value of an XML attribute, 
which are defined by the RDB_node. The XML Extender uses this mapping to determine where to store 
or retrieve the XML data. 


relational database node (RDB_node). A node that contains one or more element definitions for tables, 
optional columns, and optional conditions. The tables and columns are used to define how the XML 
data is stored in the database. The condition specifies either the criteria for selecting XML data or the 
way to join the XML collection tables. 


result set. A set of rows returned by a stored procedure. 


result table. A table which contains rows as the result of an SQL query or an execution of a stored 
procedure. 


root element. The top element of an XML document. 
root ID. A unique identifier that associates all side tables with the application table. 


SBCS. Single-byte character support. 
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scalar function. An SQL operation that produces a single value from another value and is expressed as 
a function name, followed by a list of arguments enclosed in parentheses. 


schema. A collection of database objects such as tables, views, indexes, or triggers. It provides a logical 
classification of database objects. 


search argument. The conditions specified when making a search, consisting of one or several search 
terms, and search parameters. 


section search. Provides the text search within a section which can be defined by the application. To 
support the structural text search, a section can be defined by the Xpath’s abbreviated location path. 


shot catalog. A database table or file that is used to store data about shots, such as the starting and 
ending frame number for a shot, in a video clip. A user can access a view of the table through an SQL 
query, or access the data in the file. 


side table. Additional tables created by the XML Extender to improve performance when searching 
elements or attributes in an XML column. 


simple location path. A sequence of element type names connected by a single slash (/). 


SQL mapping. A definition of the relationship of the content of an XML element or value of an XML 
attribute with relational data, using one or more SQL statements and the XSLT data model. The XML 
Extender uses the definition to determine where to store or retrieve the XML data. SOL mapping is 
defined with the SQL_stmt element in the DAD. 


static SQL. SQL statements that are embedded within a program, and are prepared during the program 
preparation process before the program is executed. After being prepared, a static SQL statement does 
not change, although values of host variables specified by the statement may change. 


stored procedure. A block of procedural constructs and embedded SQL statements that is stored in a 
database and can be called by name. Stored procedures allow an application program to be run in two 
parts. One part runs on the client and the other part runs on the server. This allows one call to produce 
several accesses to the database. 


structural text index. To index text keys based on the tree structure of the XML document, using the 
DB2 Text Extender. 


subquery. A full SELECT statement that is used within a search condition of an SQL statement. 


table space. An abstraction of a collection of containers into which database objects are stored. A table 
space provides a level of indirection between a database and the tables stored within the database. A 
table space: 


¢ Has space on media storage devices assigned to it. 


¢ Has tables created within it. These tables will consume space in the containers that belong to the table 
space. The data, index, long field, and LOB portions of a table can be stored in the same table space, 
or can be individually broken out into separate table spaces. 


terabyte. A trillion (10'*) bytes. Ten to the twelfth power bytes. When referring to memory capacity, 
1 099 511 627 776 bytes. 


text_node. A representation of the CDATA text of an element. 
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text table. A DB2 table containing text columns. 
top element_node. A representation of the root element of the XML document in the DAD. 


tracing. The action of storing information in a file that can later be used in finding the cause of an 
error. 


trigger. The definition of a set of actions to be taken when a table is changed. Triggers can be used to 
perform actions such as validating input data, automatically generating a value for a newly inserted 
row, reading from other tables for cross-referencing purposes, or writing to other tables for auditing 
purposes. Triggers are often used for integrity checking or to enforce business rules. 


trigger. A mechanism that automatically adds information about documents that need to be indexed to 
a log table whenever a document is added, changed, or deleted from a text column. 


UDE. See user-defined function. 
UDT. See user-defined type. 


uniform resource locator (URL). An address that names an HTTP server and optionally a directory and 
file name, for example: http://www.ibm.com/software/data/db2/extenders. 


UNION. An SQL operation that combines the results of two select statements. UNION is often used to 
merge lists of values that are obtained from several tables. 


URL. Uniform resource locator. 


user-defined distinct type (UDT). A data type created by a user of DB2, in contrast to a data type 
provided by DB2 such as LONG VARCHAR. 


user-defined function (UDF). A function that is defined by a user to DB2. Once defined, the function 
can be used in SQL queries. and video objects. For example, UDFs can be created to get the compression 
format of a video or return the sampling rate of an audio. This provides a way of defining the behavior 
of objects of a particular type. 


user-defined function (UDF). An SQL function created by a user of DB2, in contrast to an SQL 
function provided by DB2. Text Extender provides search functions, such as CONTAINS, in the form of 
UDFs. 


user-defined type (UDT). A data type that is defined by a user to DB2. UDTs are used to differentiate 
one LOB from another. For example, one UDT can be created for image objects and another for audio 
objects. Though stored as BLOBs, the image and audio objects are treated as types distinct from BLOBs 
and distinct from each other. 


user-defined function (UDF). A function that is defined to the database management system and can 

be referenced thereafter in SQL queries. It can be one of the following functions: 

¢ An external function, in which the body of the function is written in a programming language whose 
arguments are scalar values, and a scalar result is produced for each invocation. 

¢ A sourced function, implemented by another built-in or user-defined function that is already known 
to the DBMS. This function can be either a scalar function or column (aggregating) function, and 
returns a single value from a set of values (for example, MAX or AVG). 
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user-defined type (UDT). A data type that is not native to the database manager and was created by a 
user. See distinct type. 


user table. A table that is created for and used by an application. 


validation. The process of using a DTD to ensure that the XML document is valid and to allow 
structured searches on XML data. The DTD is stored in the DTD repository. 


valid document. An XML document that has an associated DTD. To be valid, the XML document 
cannot violate the syntactic rules specified in its DTD. 


video. Pertaining to the portion of recorded information that can be seen. 
video clip. A section of filmed or videotaped material. 
video index. A file that the Video Extender uses to find a specific shot or frame in a video clip. 


Web browser. A client program that initiates requests to a Web server and displays the information that 
the server returns. 


well-formed document. An XML document that does not contain a DTD. Although in the XML 
specification, a document with a valid DTD must also be well-formed. 


wildcard character. See masking character. 
XML. eXtensible Markup Language. 


XML attribute. Any attribute specified by the ATTLIST under the XML element in the DTD. The XML 
Extender uses the location path to identify an attribute. 


XML collection. A collection of relation tables which presents the data to compose XML documents, or 
to be decomposed from XML documents. 


XML column. A column in the application table that has been enabled for the XML Extender UDTs. 


XML element. Any XML tag or ELEMENT as specified in the XML DTD. The XML Extender uses the 
location path to identify an element. 


XML object. Equivalent to an XML document. 


XML Path Language. A language for addressing parts of an XML document. XML Path Language is 
designed to be used by XSLT. Every location path can be expressed using the syntax defined for XPath. 


XML table. An application table which includes one or more XML Extender columns. 


XML tag. Any valid XML markup language tag, mainly the XML element. The terms tag and element 
are used interchangeably. 


XML UDF. A DB2 user-defined function provided by the XML Extender. 
XML UDT. A DB2 user-defined type provided by the XML Extender. 


XPath. A language for addressing parts of an XML document. 
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XPath data model. The tree structure used to model and navigate an XML document using nodes. 
XSL. XML Stylesheet Language. 


XSLT. XML Stylesheet Language Transformation. 
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